init: TokenTrace - LLM interpretability toolbox

.cursorindexingignore

@@ -0,0 +1,3 @@
+
+# Don't index SpecStory auto-save files, but allow explicit context inclusion via @ references
+.specstory/**

.dockerignore

@@ -0,0 +1,51 @@
+# --- 核心语言与依赖 ---
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+env/
+node_modules/
+client/src/node_modules/
+client/src/.cache-loader/
+
+# --- 构建产物与缓存 ---
+client/dist/
+build/
+dist/
+*.egg-info/
+.cache_huggingface/
+*.tsbuildinfo
+
+# --- 项目特定配置 ---
+# 忽略所有数据，防止误传大文件
+data/*
+# 白名单：只保留public文件夹
+!data/demo/
+data/demo/*
+!data/demo/public/
+
+# 忽略临时文件和日志
+notes.md
+.env
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# --- 系统与 IDE ---
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# --- Git ---
+.git
+.gitignore

.gitattributes

@@ -0,0 +1,36 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+artifacts/tiny_nla/checkpoints/av/tokenizer.json filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,45 @@
+.cursor/
+.agents/
+.scratch/
+skills-lock.json
+.cache_huggingface
+# --- 核心语言与依赖 ---
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+env/
+node_modules/
+client/src/node_modules/
+client/src/.cache-loader/
+
+# --- 构建产物 ---
+client/dist/
+build/
+dist/
+*.egg-info/
+
+# --- 项目特定配置 ---
+# 忽略所有数据，防止误传大文件
+data/*
+# 白名单：只保留 GLTR 演示数据
+!data/demo/
+data/demo/*
+!data/demo/public/
+data/demo/public/.deleted/
+
+# 忽略临时笔记和 HuggingFace 缓存
+notes/*
+user_dialog_history/*
+.cache_huggingface/
+.env
+
+# --- 系统与 IDE ---
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.log
+.specstory
+scripts/log.py
+scripts/results/

.kilocode/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

.kilocode/skills/openspec-archive-change/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.kilocode/skills/openspec-explore/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │          CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.kilocode/skills/openspec-propose/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.kilocode/workflows/opsx-apply.md

@@ -0,0 +1,145 @@
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx:archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

.kilocode/workflows/opsx-archive.md

@@ -0,0 +1,150 @@
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.kilocode/workflows/opsx-explore.md

@@ -0,0 +1,166 @@
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.kilocode/workflows/opsx-propose.md

@@ -0,0 +1,99 @@
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.kiro/prompts/opsx-apply.prompt.md

@@ -0,0 +1,149 @@
+---
+description: Implement tasks from an OpenSpec change (Experimental)
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx:archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

.kiro/prompts/opsx-archive.prompt.md

@@ -0,0 +1,154 @@
+---
+description: Archive a completed change in the experimental workflow
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.kiro/prompts/opsx-explore.prompt.md

@@ -0,0 +1,170 @@
+---
+description: Enter explore mode - think through ideas, investigate problems, clarify requirements
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.kiro/prompts/opsx-propose.prompt.md

@@ -0,0 +1,103 @@
+---
+description: Propose a new change - create it and generate all artifacts in one step
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.kiro/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

.kiro/skills/openspec-archive-change/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.kiro/skills/openspec-explore/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │          CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.kiro/skills/openspec-propose/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.opencode/commands/opsx-apply.md

@@ -0,0 +1,149 @@
+---
+description: Implement tasks from an OpenSpec change (Experimental)
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx-apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx-apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx-continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx-archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

.opencode/commands/opsx-archive.md

@@ -0,0 +1,154 @@
+---
+description: Archive a completed change in the experimental workflow
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx-archive` (e.g., `/opsx-archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.opencode/commands/opsx-explore.md

@@ -0,0 +1,170 @@
+---
+description: Enter explore mode - think through ideas, investigate problems, clarify requirements
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx-explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.opencode/commands/opsx-propose.md

@@ -0,0 +1,103 @@
+---
+description: Propose a new change - create it and generate all artifacts in one step
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx-apply
+
+---
+
+**Input**: The argument after `/opsx-propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx-apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.opencode/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx-apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

.opencode/skills/openspec-archive-change/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.opencode/skills/openspec-explore/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx-explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │          CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.opencode/skills/openspec-propose/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx-apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx-apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

AGENTS.md

@@ -0,0 +1,13 @@
+## Agent skills
+
+### Issue tracker
+
+Issues live as markdown under `.scratch/<feature-slug>/`. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Five canonical roles with default label strings (no overrides). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: `CONTEXT.md` at repo root and `docs/adr/` for ADRs. See `docs/agents/domain.md`.

CONTEXT.md

@@ -0,0 +1,29 @@
+# Info Lens
+
+探索 LLM 与语言的信息结构；可视化预测、归因与生成过程。
+
+## Language
+
+**Tool call**:
+模型在生成中发出的函数调用片段，通常包在 `<tool_call>…</tool_call>` 内，含函数名与参数 JSON。本项目中默认指展示与分析用途，不执行真实工具。
+_Avoid_: function call（在与 OpenAI API 字段混用时可用，但领域讨论优先用 tool call）
+
+**Tool config**:
+用户可配置的工具集合，包含两个字段：`tools_schema`（注入 chat template 的 JSON schema 数组）和 `mock_results`（tool name → 假返回值的映射）。二者作为整体单元一起切换，避免 schema 与 mock 不一致。存储在前端 Run Draft 中，随生成参数一起持久化。
+_Avoid_: tools preset（旧称，指后端硬编码的静态配置，已废弃）、tool list
+
+**Tool calling 开关**:
+chat 模板模式下、User 输入区上方的勾选框；默认关闭。开启后显示「多轮 & mock」子开关。旧缓存与 demo 无此字段时视为关闭，不做迁移。
+_Avoid_: tool call mode、agent mode
+
+**Tool calling（单轮）**:
+在 chat template 中注入 tool config 的 schema，让模型产出 tool call 文本；不执行工具、不回灌结果。生成结果中的 tool call 与普通 token 同等对待。「多轮 & mock」关闭时的形态。
+_Avoid_: observational、agent
+
+**Tool calling（多轮）**:
+在 chat template 中注入 tool config 的 schema，解析模型产出的 tool call，用 tool config 的 mock_results 回灌假数据，再驱动下一轮生成；只要解析成功且 mock 表中有对应 tool name 就继续下一轮，否则自然结束（无 tool call、或未配置 mock 均不报错）。`<tool_call>` 存在但 JSON 无效时报错。每轮生成各自保留 bpe_strings；**wire 模型**：前端维护一条单调增长的字符串 `wire`，首轮为 `apply_chat_template` 完整 prompt（含 teacher forcing），后续每轮将模型输出与后端返回的 `incremental_suffix` 依次追加；UI 首轮 input 展示完整 `wire`，后续轮次 input 展示本轮的 `incremental_suffix`（即 tool response + generation scaffold），output 展示当轮续写全文。`incremental_suffix` 由后端 `POST /v1/completions/prompt-incremental` 通过 placeholder 技术从 chat template 中提取，与前序历史内容无关。「多轮 & mock」开启时的形态。
+_Avoid_: closed-loop、agent loop（指真实工具执行的完整代理流程）、mock agent
+
+**Causal Flow 多轮 tool calling**:
+Causal Flow 页的多轮 tool calling 形态。与 chat 页共享 wire 模型和 mock 编排逻辑，区别在于每轮用 `/api/prediction-attribute` 逐 token 生成并归因（而非 `/v1/completions` 续写）。每轮是独立的 attribution session（`startTokenGenAttribution`），由 `runMultiTurnAttribution` 编排层协调：检测 tool call 完成（`onComplete` 时）、注入 `incremental_suffix`、启动下一轮 session。所有轮次的 `TokenGenStep` 扁平合并进同一 `steps[]`，全局坐标一致（每轮 session 的 `initialContext` = 完整 wire 前缀）。**Token 语义**：只有 input（原始 prompt + 每次 tool response 注入）和 output（所有轮次模型生成的 token）两类；DAG 用 `inputRanges: [number,number][]`（`TokenGenStep` 新字段）描述 context 中哪些区间是 input，DAG 节点着色与单轮一致（input=teal，output=orange）。Cache key 在多轮开启时追加 `toolConfigFingerprint`（含 mock_results）以避免不同 mock 的 run 互相覆盖。`maxTokens` 为全局生成 token 上限（跨轮共享，非每轮独立）。Stop 打断保留已完成 steps（含当轮已归因部分），completionReason='abort'。
+_Avoid_: agent loop、closed-loop

Dockerfile

@@ -0,0 +1,67 @@
+# syntax=docker/dockerfile:1
+
+# -----------------------------------------------------------------------------
+# Frontend build stage (stable Node toolchain for webpack/TS)
+# -----------------------------------------------------------------------------
+FROM node:20-bookworm-slim AS frontend
+WORKDIR /app/client/src
+
+COPY client/src/package.json client/src/package-lock.json ./
+RUN npm ci
+
+COPY client/src/ ./
+# prebuild 需要读取的 JSON，否则 updateIntroHTML.js 会 ENOENT
+COPY data/demo/public/ /app/data/demo/public/
+RUN npm run build
+
+# -----------------------------------------------------------------------------
+# Runtime stage (Hugging Face Spaces runs container as UID 1000)
+# Reference: https://huggingface.co/docs/hub/spaces-sdks-docker
+# -----------------------------------------------------------------------------
+FROM python:3.10-slim
+
+# System deps (git for Hugging Face Hub downloads, build-essential for triton/AWQ CUDA kernel compilation)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    build-essential \
+  && rm -rf /var/lib/apt/lists/*
+
+# Create a non-root user with UID 1000 (mandatory in Spaces)
+RUN useradd -m -u 1000 user
+USER user
+
+# 只设置构建时需要的环境变量（pip install 需要这些路径）
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR $HOME/app
+
+# pip 依赖是本镜像体积与 HF 冷启动（拉取/解压 layer）的主要瓶颈：site-packages 可达数 GB，
+# 其中 torch 依赖的 site-packages/nvidia & triton 占了大部分。
+COPY --chown=user:users requirements.txt ./
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# 运行时环境变量移到依赖安装之后（这些变量不影响依赖安装）
+ENV PYTHONUNBUFFERED=1
+
+# 启用 hf-transfer 加速下载
+ENV HF_HUB_ENABLE_HF_TRANSFER=1
+
+# App source（仅复制运行时需要的路径）
+COPY --chown=user:users LICENSE NOTICE *.py *.yaml ./
+COPY --chown=user:users backend/ ./backend/
+COPY --chown=user:users data/demo/public/ ./data/demo/public/
+
+# Frontend build artifacts
+COPY --chown=user:users --from=frontend /app/client/dist ./client/dist
+
+# ENV FORCE_INT8=1
+
+EXPOSE 7860
+# 硬件的模型适配：
+# 在CPU basic 上使用0.6b模型能达到及格的速度
+# 在CPU upgrade 上使用1.7b模型能达到及格的速度
+# 在本地M5 16G芯片上使用4b模型能达到及格的速度（瓶颈是内存大小）；M5 16G内存仅能同时支持一种分析模型（信息密度分析或语义分析）
+CMD ["python", "run.py", "--no_auto_load", "--port", "7860", "--base_model", "qwen3-1.7b", "--instruct_model", "qwen3-1.7b-instruct"]
+# CMD ["python", "run.py", "--no_auto_load", "--port", "7860", "--base_model", "qwen3-0.6b", "--instruct_model", "qwen3-0.6b-instruct"]

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -0,0 +1,8 @@
+Info Lens (Info Highlight)
+Copyright 2025-2026 dqy <xiaoyundqy@qq.com>
+
+Project: https://huggingface.co/spaces/dqy08/InfoLens
+
+This product includes software from the GLTR project (Apache-2.0):
+Copyright 2019 Hendrik Strobelt, Sebastian Gehrmann, Alexander M. Rush
+https://github.com/HendrikStrobelt/detecting-fake-text

README.md

@@ -0,0 +1,148 @@
+---
+title: TokenTrace
+emoji: 🔬
+colorFrom: blue
+colorTo: purple
+sdk: docker
+short_description: Trace how LLMs think — token attribution, logit lens, semantic analysis & more
+tags:
+  - nlp
+  - text-analysis
+  - llm-interpretability
+  - visualization
+  - mechanistic-interpretability
+app_port: 7860
+pinned: false
+license: apache-2.0
+---
+
+# TokenTrace 🔬
+
+> *Trace how every token shapes an LLM's predictions.*
+
+**🌐 Live Demo**: [huggingface.co/spaces/Girlz/TokenTrace](https://huggingface.co/spaces/Girlz/TokenTrace)
+
+**TokenTrace** is an interactive toolbox for exploring **how and why LLMs predict what they do**. It visualizes token-level attributions, layer-by-layer information flow, semantic relevance, and generation branching — all through a beautiful web UI.
+
+---
+
+## ✨ Features
+
+### 🎯 Prediction Attribution
+See which tokens in your input most influenced the model's next-token prediction. Uses gradient-based saliency (L2 norm of embedding gradients) to rank each token's contribution.
+
+### 🔪 Ablation Attribution
+Measure the impact of each token by occluding it and observing the probability change (ΔP = baseline − occluded). A counterfactual approach to understanding token importance.
+
+### 📊 Logit Lens
+Watch how the model's prediction "crystallizes" layer by layer. Each Transformer layer's hidden state is projected back to vocabulary space, revealing how information accumulates through the network depth.
+
+### 🌳 Branch Tree
+Visualize the top-k candidate tokens at every step of generation. Explore alternative paths the model could have taken — a probability tree that reveals the model's uncertainty and decision landscape.
+
+### 📝 Information Density Analysis
+Analyze which tokens carry the most "information content" using gradient-based methods. Distinguish high-information tokens (nouns, verbs) from low-information ones (stop words, punctuation).
+
+### 🔍 Semantic Relevance Analysis
+Given a query, score every token in a text by its relevance to that query. Uses logits gradient with a fill-in-the-blank prompt strategy to extract fine-grained relevance scores.
+
+### 💬 Chat & Generation
+OpenAI-compatible completions endpoint with SSE streaming. Supports chat templates, tool calling visualization, and multi-turn causal flow tracing.
+
+### 🔄 Causal Flow
+Multi-turn generation with per-token attribution at every step. Trace the full causal chain from input to output across multiple rounds of tool calling and generation.
+
+---
+
+## 🚀 Quick Start
+
+### Run Locally with Docker
+
+```bash
+# 1. Build the image
+docker build -t tokentrace .
+
+# 2. Run the container
+docker run -p 7860:7860 tokentrace
+
+# 3. Visit http://localhost:7860
+```
+
+### Local Development
+
+```bash
+# Backend
+pip install -r requirements.txt
+python run.py --no_auto_load --base_model qwen3-0.6b --instruct_model qwen3-0.6b-instruct
+
+# Frontend (separate terminal)
+cd client/src && npm install && npm run build
+```
+
+---
+
+## 🧠 How It Works
+
+```mermaid
+flowchart LR
+    U[User Input] --> A[TokenTrace Backend]
+    A --> M1[Base Model Slot<br/>Qwen3-0.6B-Base]
+    A --> M2[Instruct Model Slot<br/>Qwen3-0.6B]
+    M1 -->|forward + backward| G[Gradient Attribution]
+    M1 -->|forward pass| L[Logit Lens]
+    M1 -->|forward + occlusion| AB[Ablation Attribution]
+    M1 -->|forward + softmax| BT[Branch Tree]
+    M2 -->|chat template + generate| C[Chat / Completion]
+    M2 -->|gradient + prompt| S[Semantic Analysis]
+    G --> V[JSON Result → Frontend Visualization]
+    L --> V
+    AB --> V
+    BT --> V
+    C --> V
+    S --> V
+```
+
+The backend runs two model slots in PyTorch:
+- **Base slot**: For analysis tasks (attribution, logit lens, branching) — Qwen3-0.6B-Base
+- **Instruct slot**: For chat and semantic analysis — Qwen3-0.6B
+
+All analysis is done locally on CPU (free tier) or GPU (if available), with gradient checkpointing to minimize memory usage.
+
+---
+
+## 🗺️ Feature Map
+
+| Page | Path | Purpose | Requires |
+|------|------|---------|----------|
+| Home | `/` | Overview & navigation | Static |
+| Analysis | `/client/analysis.html` | Information density & semantic analysis | Base slot |
+| Attribution | `/client/attribution.html` | Prediction & ablation attribution | Base slot |
+| Chat | `/client/chat.html` | Chat completion with tool calling | Instruct slot |
+| Logit Lens | `/client/logit_lens.html` | Layer-by-layer prediction projection | Base slot |
+| Branch Tree | `/client/branch_tree.html` | Next-token probability tree | Base slot |
+| Causal Flow | `/client/causal_flow.html` | Multi-turn generation + attribution | Both slots |
+
+---
+
+## ⚙️ Configuration
+
+Key environment variables:
+
+| Variable | Purpose |
+|----------|---------|
+| `FORCE_INT8=1` | Enable INT8 quantization (CPU, saves ~50% memory) |
+| `FORCE_CPU=1` | Force CPU mode |
+| `HF_HUB_ENABLE_HF_TRANSFER=1` | Accelerate model downloads |
+| `INFORADAR_ADMIN_TOKEN` | Admin token for model switching & demo management |
+
+---
+
+## 📜 License
+
+[Apache 2.0](LICENSE). Copyright and attribution notices remain in [NOTICE](NOTICE).
+
+---
+
+## 🙏 Fork Attribution
+
+This project is forked from [InfoLens](https://huggingface.co/spaces/dqy08/InfoLens) by [dqy08](https://huggingface.co/dqy08), with enhancements and adaptations for the Hugging Face Spaces free tier.

backend/__init__.py

@@ -0,0 +1,5 @@
+from backend.models import REGISTERED_MODELS
+
+import backend.core.language_checker  # noqa: F401
+
+__all__ = ["REGISTERED_MODELS"]

backend/api/__init__.py

@@ -0,0 +1,2 @@
+"""API 路由模块"""
+

backend/api/ablation_attribute.py

@@ -0,0 +1,135 @@
+"""消融归因 API"""
+import gc
+import time
+
+from backend.models.model_manager import inference_lock
+from backend.platform.oom import exit_if_oom
+from backend.core.ablation_attributor import analyze_ablation_attribution
+from backend.api.analyze import LOCK_WAIT_TIMEOUT
+from backend.platform.access_log import get_client_ip, log_prediction_attribute_request
+from backend.platform.source_page import ALLOWED_SOURCE_PAGES, normalize_source_page
+
+
+def ablation_attribute(ablation_request):
+    """
+    对上下文文本的下一 token 预测做消融归因。
+
+    Args:
+        ablation_request: 须含 ``context``、``model``、``source_page``。
+            归因目标三选一：省略两者时为 top-1；
+            ``target_prediction``（首 token）；``target_token_id``（非负整数）；二者互斥。
+
+    Returns:
+        (响应字典, 状态码) 元组
+    """
+    context = ablation_request.get("context")
+    target_prediction = ablation_request.get("target_prediction")
+    target_token_id = ablation_request.get("target_token_id")
+    model = ablation_request.get("model")
+    source_page = ablation_request.get("source_page")
+    flow_id = ablation_request.get("flow_id")
+    flow_step = ablation_request.get("flow_step")
+
+    if context is None or context == "":
+        return {"success": False, "message": "Missing required field: context"}, 400
+    if not isinstance(context, str):
+        return {"success": False, "message": "context must be a string"}, 400
+
+    if target_prediction is not None and not isinstance(target_prediction, str):
+        return {"success": False, "message": "target_prediction must be a string"}, 400
+    if target_prediction == "":
+        return {"success": False, "message": "target_prediction must not be empty"}, 400
+    if target_token_id is not None and not isinstance(target_token_id, int):
+        return {"success": False, "message": "target_token_id must be an integer"}, 400
+    if target_token_id is not None and target_token_id < 0:
+        return {"success": False, "message": "target_token_id must be >= 0"}, 400
+    if target_prediction is not None and target_token_id is not None:
+        return {"success": False, "message": "target_prediction and target_token_id are mutually exclusive"}, 400
+
+    if model is None:
+        return {"success": False, "message": "Missing required field: model"}, 400
+    if model not in ("base", "instruct"):
+        return {"success": False, "message": 'model must be "base" or "instruct"'}, 400
+
+    if source_page is None or source_page == "":
+        return {"success": False, "message": "Missing required field: source_page"}, 400
+    normalized_source_page = normalize_source_page(source_page)
+    if normalized_source_page is None:
+        allowed = ", ".join(sorted(ALLOWED_SOURCE_PAGES))
+        return {
+            "success": False,
+            "message": f"source_page must be one of: {allowed} (legacy *.html and gen_attribute accepted)",
+        }, 400
+    source_page = normalized_source_page
+
+    if flow_id is not None and not isinstance(flow_id, str):
+        return {"success": False, "message": "flow_id must be a string"}, 400
+    if flow_id == "":
+        return {"success": False, "message": "flow_id must not be empty"}, 400
+    if flow_step is not None and not isinstance(flow_step, int):
+        return {"success": False, "message": "flow_step must be an integer"}, 400
+    if flow_step is not None and flow_step < 0:
+        return {"success": False, "message": "flow_step must be >= 0"}, 400
+
+    is_causal_flow = source_page == "causal_flow"
+    if is_causal_flow:
+        if flow_id is None:
+            return {"success": False, "message": "Missing required field: flow_id for causal flow"}, 400
+        if flow_step is None:
+            return {"success": False, "message": "Missing required field: flow_step for causal flow"}, 400
+    elif flow_id is not None or flow_step is not None:
+        return {
+            "success": False,
+            "message": "flow_id/flow_step are only allowed when source_page is causal_flow",
+        }, 400
+
+    client_ip = get_client_ip()
+    start_time = time.perf_counter()
+    request_id = log_prediction_attribute_request(
+        context=context,
+        target_prediction=target_prediction,
+        target_token_id=target_token_id,
+        model=model,
+        source_page=source_page,
+        flow_id=flow_id,
+        flow_step=flow_step,
+        client_ip=client_ip,
+    )
+
+    lock_acquired = inference_lock.acquire(timeout=LOCK_WAIT_TIMEOUT)
+    if not lock_acquired:
+        return {
+            "success": False,
+            "message": (
+                f"Queue wait exceeded {LOCK_WAIT_TIMEOUT} seconds; "
+                "server is busy, please try again later."
+            ),
+        }, 503
+
+    try:
+        result = analyze_ablation_attribution(
+            context,
+            target_prediction,
+            model=model,
+            target_token_id=target_token_id,
+        )
+    except ValueError as e:
+        return {"success": False, "message": str(e)}, 400
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        exit_if_oom(e, defer_seconds=1)
+        return {"success": False, "message": str(e)}, 500
+    finally:
+        inference_lock.release()
+        gc.collect()
+
+    elapsed = time.perf_counter() - start_time
+    tokens = len(result.get("token_attribution", []))
+    target_token = result.get("target_token")
+    print(
+        f"\t📤 API ablation_attribute response: req_id={request_id}, "
+        f"target={target_token!r}, tokens={tokens}, response_time={elapsed:.4f}s"
+    )
+
+    return {"success": True, **result}, 200

backend/api/analyze.py

@@ -0,0 +1,412 @@
+"""文本分析 API"""
+import gc
+import json
+import time
+import queue
+import threading
+from typing import Optional
+from backend.platform.schemas import create_empty_analysis_result
+from backend.models.model_manager import project_registry, DEFAULT_BASE_MODEL, inference_lock
+from model_paths import resolve_hf_path
+from backend.platform.oom import exit_if_oom
+from backend.api.sse_utils import (
+    SSEProgressReporter,
+    consume_progress_queue,
+    send_result_event,
+    send_error_event,
+)
+
+
+# 自定义异常：排队超时
+class QueueTimeoutError(Exception):
+    """排队等待获取锁超时"""
+    pass
+
+
+# 使用 model_manager 中的统一推理锁（与 analyze_semantic 共用）
+# 单次分析的总处理时长限制（秒）
+ANALYSIS_TIMEOUT = 60.0
+# 等待获取锁的最大时间（秒）- 如果排队时间过长，直接拒绝请求
+LOCK_WAIT_TIMEOUT = 10.0
+
+
+def _analyze_result_model_display(model: Optional[str]) -> Optional[str]:
+    """主分析 result.model：对外统一为 HuggingFace 仓库 id（与 model_paths.resolve_hf_path 一致）。"""
+    if not model or not str(model).strip():
+        return None
+    return resolve_hf_path(str(model).strip())
+
+
+def _build_response(model: str, text: str, result):
+    """构建标准响应"""
+    # 将 model 添加到 result 中，并确保 model 在最前面
+    if not isinstance(result, dict):
+        result = {}
+    result = result.copy()
+    # 如果 result 中已有 model，先移除
+    if 'model' in result:
+        model_value = result.pop('model')
+    else:
+        model_value = model
+    # 重新构建 result，确保 model 在最前面
+    result = {'model': _analyze_result_model_display(model_value), **result}
+    return {
+        "request": {'text': text},
+        "result": result
+    }
+
+
+def _error_response(model: str, text: str, message: str, status_code: int):
+    """构建错误响应（统一格式）"""
+    # 统一错误格式：包含 success=false 和 message
+    result = create_empty_analysis_result(message, _analyze_result_model_display(model))
+    return {
+        "success": False,
+        "message": message,
+        "request": {'text': text or ''},
+        "result": result
+    }, status_code
+
+
+def _validate_and_prepare_request(analyze_request):
+    """
+    验证请求并准备参数
+    
+    Returns:
+        (model, text, error_msg, status_code) 元组
+        如果验证失败，返回 (None, None, error_msg, status_code)
+        如果成功，返回 (model, text, None, None)
+    """
+    model = analyze_request.get('model')
+    text = analyze_request.get('text')
+    
+    if not text:
+        return None, None, "缺少分析文本，请提供 text 字段", 400
+    
+    # 获取默认模型（使用模块级上下文以获取持久化的当前活动模型）
+    from backend.platform.app_context import get_app_context
+    context = get_app_context(prefer_module_context=True)
+    default_model = context.base_model_id if context.base_model_id else DEFAULT_BASE_MODEL
+    
+    # 处理 default、None 或空字符串，使用默认模型
+    if not model or model == 'default' or model == '':
+        model = default_model
+    else:
+        # 只允许使用默认模型，其他模型请求将被拒绝
+        if model != default_model:
+            return None, None, f"当前仅支持默认模型 '{default_model}'，不允许使用其他模型", 400
+    
+    return model, text, None, None
+
+
+def _load_project_with_error_handling(model):
+    """
+    获取已加载的模型；若未加载则根据配置进行懒加载或返回错误。
+    
+    Returns:
+        (project_obj, error_msg, status_code) 元组
+        如果成功，返回 (project_obj, None, None)
+        如果失败，返回 (None, error_msg, status_code)
+    """
+    # 检查模型是否在注册表中
+    if not project_registry.is_available(model):
+        available_models = list(project_registry.available_model_names())
+        error_msg = f"❌ 模型 '{model}' 未注册。可用模型: {available_models}"
+        print(error_msg)
+        return None, error_msg, 404
+    
+    # 检查模型是否已加载
+    p = project_registry.get(model)
+    if p is None:
+        from backend.platform.app_context import get_app_context
+        from backend.models.model_manager import ensure_base_slot_ready
+
+        context = get_app_context(prefer_module_context=True)
+        if context.model_loading:
+            error_msg = f"模型 '{model}' 正在后台加载中，请稍后重试"
+            print(f"⚠️ {error_msg}")
+            return None, error_msg, 503
+        # 懒加载模式 (--no_auto_load)：首次请求仅初始化主槽位（权重 + QwenLM 项目）
+        if getattr(context.args, 'no_auto_load', False):
+            try:
+                ensure_base_slot_ready()
+                p = project_registry.get(model)
+            except Exception as e:  # noqa: BLE001
+                import traceback
+                print(f"⚠️ 模���懒加载失败: {e}")
+                traceback.print_exc()
+                return None, f"模型加载失败: {str(e)}", 500
+        if p is None:
+            error_msg = f"模型 '{model}' 未加载，请联系管理员"
+            print(f"⚠️ {error_msg}")
+            return None, error_msg, 503
+    return p, None, None
+
+
+def _log_request(text, stream_mode=False, client_ip=None):
+    """
+    打印请求日志
+    
+    Returns:
+        int: 请求ID
+    """
+    from backend.platform.access_log import log_analyze_request
+    return log_analyze_request(text, stream_mode, client_ip)
+
+
+def _log_response(res, char_count, elapsed_time, stream_mode=False, request_id=None, wait_time=None):
+    """打印响应日志"""
+    tokens = len(res.get('bpe_strings', []))
+    text_length = char_count
+    mode_str = "(stream)" if stream_mode else ""
+    
+    # 构建日志消息
+    msg = f"\t📤 API analyze {mode_str} response:"
+    if request_id is not None:
+        msg += f" req_id={request_id},"
+    msg += f" tokens={tokens}, text_length={text_length}"
+    msg += f", response_time={elapsed_time:.4f}s"
+    
+    print(msg)
+
+
+def _validate_and_fix_result(res):
+    """验证和修复结果结构"""
+    if not isinstance(res, dict):
+        res = {'bpe_strings': []}
+    if 'bpe_strings' not in res or not isinstance(res.get('bpe_strings'), list):
+        res['bpe_strings'] = res.get('bpe_strings', []) if isinstance(res.get('bpe_strings'), list) else []
+    return res
+
+
+def analyze(analyze_request):
+    """
+    分析文本
+
+    Args:
+        analyze_request: 分析请求字典，包含：
+            - model: 模型名称
+            - text: 要分析的文本
+            - stream: 可选，如果为 True 则返回 SSE 流式响应（带进度信息）
+
+    Returns:
+        如果 stream=True: SSE 响应对象
+        否则: (响应字典, 状态码) 元组
+    """
+    # 检查模型是否正在加载中（使用模块级上下文）
+    from backend.platform.app_context import get_app_context
+    context = get_app_context(prefer_module_context=True)
+    if context.model_loading:
+        return _error_response('', '', '模型正在加载中，请稍后重试', 503)
+
+    # 在请求上下文中获取 client_ip，流式响应时生成器内可能已失效
+    from backend.platform.access_log import get_client_ip
+    client_ip = get_client_ip()
+
+    # 检查是否启用流式响应
+    stream = analyze_request.get('stream', False)
+    if stream:
+        return _analyze_with_stream(analyze_request, client_ip)
+    return _analyze_plain(analyze_request, client_ip)
+
+
+def _analyze_with_stream(analyze_request, client_ip):
+    """
+    流式分析文本，通过SSE返回进度和结果（内部函数）
+
+    Args:
+        analyze_request: 分析请求字典，包含 model 和 text
+        client_ip: 客户端 IP，在入口处获取后传入
+
+    Returns:
+        SSE响应对象
+    """
+    reporter = SSEProgressReporter(lambda: _generate_analyze_events(analyze_request, client_ip))
+    return reporter.create_response()
+
+
+def _analyze_plain(analyze_request, client_ip):
+    """
+    非流式分析：封装流式实现，消费事件流后返回 JSON。
+    供脚本等简单客户端使用。
+    """
+    result = None
+    error_msg = None
+    status_code = 500
+    try:
+        for event_str in _generate_analyze_events(analyze_request, client_ip):
+            if not event_str.startswith('data: '):
+                continue
+            data = json.loads(event_str[6:].strip())
+            t = data.get('type')
+            if t == 'result':
+                result = data.get('data')
+            elif t == 'error':
+                error_msg = data.get('message', '分析失败')
+                status_code = data.get('status_code', 500)
+                break
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        exit_if_oom(e, defer_seconds=1)
+        error_msg = f"分析失败: {str(e)}"
+    finally:
+        gc.collect()
+
+    if error_msg:
+        model = analyze_request.get('model') or ''
+        text = analyze_request.get('text') or ''
+        return _error_response(model, text, error_msg, status_code)
+    if result is None:
+        return _error_response('', '', '分析失败：未获取到结果', 500)
+    return result, 200
+
+
+def _generate_analyze_events(analyze_request, client_ip):
+    """
+    流式分析核心：生成 SSE 事件流（progress + result/error）。
+    供 _analyze_with_stream 和 _analyze_plain 复用。
+    client_ip 需在入口处获取并传入，因流式响应时生成器执行时请求上下文可能已失效。
+    """
+    # 再次检查模型加载状态（在生成器内部，使用模块级上下文）
+    from backend.platform.app_context import get_app_context
+    context = get_app_context(prefer_module_context=True)
+    if context.model_loading:
+        yield send_error_event('模型正在加载中，请稍后重试', 503)
+        return
+
+    start_time = time.perf_counter()
+
+    # 验证和准备请求
+    model, text, error_msg, status_code = _validate_and_prepare_request(analyze_request)
+    if error_msg:
+        yield send_error_event(error_msg, status_code or 400)
+        return
+
+    # 加载模型
+    p, error_msg, status_code = _load_project_with_error_handling(model)
+    if error_msg:
+        yield send_error_event(error_msg, status_code or 500)
+        return
+
+    try:
+        char_count = len(text) if text else 0
+        request_id = _log_request(text, stream_mode=True, client_ip=client_ip)
+
+        # 创建线程安全的进度队列
+        progress_queue = queue.Queue()
+        analysis_done = threading.Event()
+        analysis_result = None
+        analysis_error = None
+        lock_wait_time = None  # 记录等待锁的时间
+
+        def progress_callback_func(step: int, total_steps: int, stage: str, percentage: Optional[int]):
+            """进度回调函数，将事件加入队列"""
+            progress_queue.put(('progress', step, total_steps, stage, percentage))
+
+        def run_analysis():
+            """在单独线程中运行分析"""
+            nonlocal analysis_result, analysis_error, lock_wait_time
+            try:
+                # 记录开始等待锁的时间
+                lock_wait_start = time.perf_counter()
+
+                # 尝试获取锁，设置超时避免长时间排队
+                lock_acquired = inference_lock.acquire(timeout=LOCK_WAIT_TIMEOUT)
+                if not lock_acquired:
+                    # 获取锁超时，说明前面有任务在执行且耗时较长
+                    analysis_error = QueueTimeoutError(
+                        f"排队等待超过 {LOCK_WAIT_TIMEOUT} 秒，服务繁忙，请稍后重试"
+                    )
+                    return
+
+                # 记录等待时间
+                lock_wait_time = time.perf_counter() - lock_wait_start
+
+                try:
+                    from backend.platform.access_log import log_analyze_start
+                    log_analyze_start(request_id, lock_wait_time, stream_mode=True)
+
+                    # 在持有锁的情况下执行分析
+                    # 注意：这里的执行时长也会受到 ANALYSIS_TIMEOUT 的监控（在外层循环中）
+                    res = p.lm.analyze_text(text, progress_callback=progress_callback_func)
+                    analysis_result = res
+                finally:
+                    # 确保锁一定会被释放
+                    inference_lock.release()
+            except Exception as e:
+                analysis_error = e
+            finally:
+                analysis_done.set()
+                progress_queue.put(('done', None, None))  # 发送完成信号
+
+        # 启动分析线程
+        analysis_thread = threading.Thread(target=run_analysis, daemon=True)
+        analysis_thread.start()
+
+        # 实时发送进度事件，并检查超时
+        timeout_reached = False
+        for kind, event_str in consume_progress_queue(
+            progress_queue, analysis_done, start_time, ANALYSIS_TIMEOUT, "分析"
+        ):
+            if kind == 'timeout':
+                timeout_reached = True
+                yield event_str
+                break
+            if kind == 'progress':
+                yield event_str
+            elif kind == 'done':
+                break
+
+        # 如果超时，不等待分析完成，直接返回
+        if timeout_reached:
+            gc.collect()
+            return
+
+        # 检查是否有错误
+        # 注意：此时已收到 'done' 信号，分析线程已完成其工作（或发生错误）
+        # 线程是 daemon 的，会自动清理，无需显式等待
+        if analysis_error:
+            # 排队超时：返回友好的错误消息
+            if isinstance(analysis_error, QueueTimeoutError):
+                print(f"⏱️ 排队超时: {analysis_error}")
+                yield send_error_event(str(analysis_error), 503)
+                gc.collect()
+                return
+            # 其他错误：抛出异常，由外层的 try-except 处理
+            raise analysis_error
+
+        # 检查结果是否为空（理论上不应该发生，因为要么有结果，要么有错误）
+        if analysis_result is None:
+            print("⚠️ 分析结果为空，但没有错误信息")
+            yield send_error_event("分析失败：未获取到结果", 500)
+            gc.collect()
+            return
+
+        res = analysis_result
+
+        elapsed_time = time.perf_counter() - start_time
+        _log_response(res, char_count, elapsed_time, stream_mode=True,
+                     request_id=request_id, wait_time=lock_wait_time)
+
+        # 验证和修复结果
+        res = _validate_and_fix_result(res)
+
+        # 构建最终响应
+        final_response = _build_response(model, text, res)
+
+        # 发送最终结果
+        yield send_result_event(final_response)
+
+        # 强制垃圾回收以释放内存
+        gc.collect()
+
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        exit_if_oom(e, defer_seconds=1)
+        yield send_error_event(str(e), 500)
+        # 即使出错也进行垃圾回收
+        gc.collect()
+
+

backend/api/analyze_semantic.py

@@ -0,0 +1,212 @@
+"""Semantic analysis API：返回原文各 token 对 prompt 的平均关注度"""
+import gc
+import json
+import queue
+import threading
+import time
+from typing import Optional
+
+from backend.models.model_manager import inference_lock
+from backend.platform.oom import exit_if_oom
+from backend.core.semantic_analyzer import analyze_semantic as _analyze_semantic
+from backend.api.sse_utils import (
+    SSEProgressReporter,
+    consume_progress_queue,
+    send_result_event,
+    send_error_event,
+)
+from backend.platform.access_log import get_client_ip
+from backend.api.analyze import QueueTimeoutError, ANALYSIS_TIMEOUT, LOCK_WAIT_TIMEOUT
+
+
+def _log_request(query, text, client_ip=None):
+    from backend.platform.access_log import log_analyze_semantic_request
+    return log_analyze_semantic_request(query, text, client_ip)
+
+
+def _build_success_response(result, debug_info: bool = False):
+    """构建成功响应。debug_info=True 时包含 debug_info 对象（abbrev、topk_tokens、topk_probs）"""
+    resp = {
+        "success": True,
+        "model": result["model"],
+        "token_attention": result["token_attention"],
+        "full_match_degree": result["full_match_degree"],
+    }
+    if debug_info and "debug_info" in result:
+        resp["debug_info"] = result["debug_info"]
+    return resp
+
+
+def _generate_semantic_events(
+    query: str, text: str, submode: Optional[str] = None, debug_info: bool = False,
+    full_match_degree_only: bool = False, client_ip: Optional[str] = None
+):
+    """
+    流式语义分析核心：生成 SSE 事件流（progress + result/error）。
+    供 _analyze_semantic_with_stream 和 _analyze_semantic_plain 复用。
+    client_ip 需在入口处获取并传入，因流式响应时生成器执行时请求上下文已失效。
+    """
+    if client_ip is None:
+        client_ip = get_client_ip()
+    start_time = time.perf_counter()
+    request_id = _log_request(query, text, client_ip)
+
+    progress_queue = queue.Queue()
+    analysis_done = threading.Event()
+    analysis_result = None
+    analysis_error = None
+    lock_wait_time = None
+
+    def progress_callback(step: int, total_steps: int, stage: str, percentage: Optional[int]):
+        progress_queue.put(("progress", step, total_steps, stage, percentage))
+
+    def run_analysis():
+        nonlocal analysis_result, analysis_error, lock_wait_time
+        try:
+            lock_wait_start = time.perf_counter()
+            lock_acquired = inference_lock.acquire(timeout=LOCK_WAIT_TIMEOUT)
+            if not lock_acquired:
+                analysis_error = QueueTimeoutError(
+                    f"排队等待超过 {LOCK_WAIT_TIMEOUT} 秒，服务繁忙，请稍后重试"
+                )
+                return
+            lock_wait_time = time.perf_counter() - lock_wait_start
+
+            try:
+                from backend.platform.access_log import log_analyze_semantic_start
+                log_analyze_semantic_start(request_id, lock_wait_time, stream_mode=True)
+                result = _analyze_semantic(query, text, submode_override=submode, progress_callback=progress_callback, debug_info=debug_info, full_match_degree_only=full_match_degree_only)
+                analysis_result = result
+            finally:
+                inference_lock.release()
+        except Exception as e:
+            analysis_error = e
+        finally:
+            analysis_done.set()
+            progress_queue.put(("done", None, None))
+
+    try:
+        analysis_thread = threading.Thread(target=run_analysis, daemon=True)
+        analysis_thread.start()
+
+        timeout_reached = False
+        for kind, event_str in consume_progress_queue(
+            progress_queue, analysis_done, start_time, ANALYSIS_TIMEOUT, "语义分析"
+        ):
+            if kind == 'timeout':
+                timeout_reached = True
+                yield event_str
+                break
+            if kind == 'progress':
+                yield event_str
+            elif kind == 'done':
+                break
+
+        if timeout_reached:
+            gc.collect()
+            return
+
+        if analysis_error:
+            if isinstance(analysis_error, QueueTimeoutError):
+                print(f"⏱️ 排队超时: {analysis_error}")
+                yield send_error_event(str(analysis_error), 503)
+                gc.collect()
+                return
+            raise analysis_error
+
+        if analysis_result is None:
+            print("⚠️ 语义分析结果为空，但没有错误信息")
+            yield send_error_event("分析失败：未获取到结果", 500)
+            gc.collect()
+            return
+
+        elapsed = time.perf_counter() - start_time
+        tokens = len(analysis_result.get("token_attention", []))
+        print(
+            f"\t📤 API analyze_semantic (stream) response: req_id={request_id}, "
+            f"tokens={tokens}, response_time={elapsed:.4f}s"
+        )
+        yield send_result_event(_build_success_response(analysis_result, debug_info))
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        exit_if_oom(e, defer_seconds=1)
+        yield send_error_event(str(e), 500)
+    finally:
+        gc.collect()
+
+
+def _analyze_semantic_with_stream(
+    query: str, text: str, submode: Optional[str] = None, debug_info: bool = False,
+    full_match_degree_only: bool = False, client_ip: Optional[str] = None
+):
+    """流式语义分析，通过 SSE 返回阶段级进度"""
+    return SSEProgressReporter(
+        lambda: _generate_semantic_events(query, text, submode, debug_info, full_match_degree_only, client_ip)
+    ).create_response()
+
+
+def _analyze_semantic_plain(
+    query: str, text: str, submode: Optional[str] = None, debug_info: bool = False,
+    full_match_degree_only: bool = False, client_ip: Optional[str] = None
+):
+    """
+    非流式语义分析：封装流式实现，消费事件流后返回 JSON。
+    供脚本等简单客户端使用。
+    """
+    result = None
+    error_msg = None
+    status_code = 500
+    try:
+        for event_str in _generate_semantic_events(query, text, submode, debug_info, full_match_degree_only, client_ip):
+            if not event_str.startswith('data: '):
+                continue
+            data = json.loads(event_str[6:].strip())
+            t = data.get('type')
+            if t == 'result':
+                result = data.get('data')
+            elif t == 'error':
+                error_msg = data.get('message', '分析失败')
+                status_code = data.get('status_code', 500)
+                break
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        exit_if_oom(e, defer_seconds=1)
+        error_msg = str(e)
+    finally:
+        gc.collect()
+
+    if error_msg:
+        return {"success": False, "message": error_msg}, status_code
+    if result is None:
+        return {"success": False, "message": "分析失败：未获取到结果"}, 500
+    return result, 200
+
+
+def analyze_semantic(semantic_request):
+    """
+    分析原文 token 对 prompt 的关注度。
+
+    Args:
+        semantic_request: 包含 query、text、stream（可选）、submode（可选）的字典
+
+    Returns:
+        stream=True 时返回 SSE 响应；否则返回 (响应字典, 状态码) 元组
+    """
+    query = (semantic_request.get("query") or "")
+    text = semantic_request.get("text") or ""
+    stream = semantic_request.get("stream", False)
+    submode = (semantic_request.get("submode") or "").strip() or None
+    debug_info = bool(semantic_request.get("debug_info", False))
+    full_match_degree_only = bool(semantic_request.get("full_match_degree_only", False))
+
+    if not query:
+        return {"success": False, "message": "缺少 query 字段"}, 400
+    if not text:
+        return {"success": False, "message": "缺少 text 字段"}, 400
+
+    client_ip = get_client_ip()
+    if stream:
+        return _analyze_semantic_with_stream(query, text, submode, debug_info, full_match_degree_only, client_ip)
+    return _analyze_semantic_plain(query, text, submode, debug_info, full_match_degree_only, client_ip)

backend/api/branch_next.py

@@ -0,0 +1,81 @@
+"""分叉树 branch-next API"""
+import gc
+import time
+
+from backend.models.model_manager import inference_lock
+from backend.platform.oom import exit_if_oom
+from backend.core.branch_next import expand_branch_next, BRANCH_NEXT_TOP_K_MAX
+from backend.core.completion_generator import PromptTooLongError
+from backend.api.analyze import LOCK_WAIT_TIMEOUT
+from backend.platform.access_log import get_client_ip, log_request
+from backend.platform.source_page import ALLOWED_SOURCE_PAGES, normalize_source_page
+
+
+def branch_next(branch_next_request):
+    prefix = branch_next_request.get("prefix")
+    model = branch_next_request.get("model")
+    source_page = branch_next_request.get("source_page")
+    top_k = branch_next_request.get("top_k")
+
+    if prefix is None or prefix == "":
+        return {"success": False, "message": "Missing required field: prefix"}, 400
+    if not isinstance(prefix, str):
+        return {"success": False, "message": "prefix must be a string"}, 400
+
+    if model is None:
+        return {"success": False, "message": "Missing required field: model"}, 400
+    if model not in ("base", "instruct"):
+        return {"success": False, "message": 'model must be "base" or "instruct"'}, 400
+
+    if source_page is None or source_page == "":
+        return {"success": False, "message": "Missing required field: source_page"}, 400
+    normalized_source_page = normalize_source_page(source_page)
+    if normalized_source_page is None:
+        allowed = ", ".join(sorted(ALLOWED_SOURCE_PAGES))
+        return {"success": False, "message": f"source_page must be one of: {allowed}"}, 400
+    source_page = normalized_source_page
+
+    if top_k is not None:
+        if not isinstance(top_k, int):
+            return {"success": False, "message": "top_k must be an integer"}, 400
+        if top_k < 1:
+            return {"success": False, "message": f"top_k must be >= 1"}, 400
+        if top_k > BRANCH_NEXT_TOP_K_MAX:
+            # clamp 而不是报错（设计 D3）
+            top_k = BRANCH_NEXT_TOP_K_MAX
+
+    client_ip = get_client_ip()
+    start_time = time.perf_counter()
+    log_request("📥 branch_next 请求", f"model={model!r}, source_page={source_page!r}, prefix_chars={len(prefix)}", client_ip)
+
+    lock_acquired = inference_lock.acquire(timeout=LOCK_WAIT_TIMEOUT)
+    if not lock_acquired:
+        return {"success": False, "message": f"Queue wait exceeded {LOCK_WAIT_TIMEOUT} seconds; server is busy, please try again later."}, 503
+
+    kwargs = {"model": model}
+    if top_k is not None:
+        kwargs["top_k"] = top_k
+
+    try:
+        result = expand_branch_next(prefix, **kwargs)
+    except PromptTooLongError as e:
+        return {"success": False, "message": str(e)}, 400
+    except ValueError as e:
+        return {"success": False, "message": str(e)}, 400
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        exit_if_oom(e, defer_seconds=1)
+        return {"success": False, "message": str(e)}, 500
+    finally:
+        inference_lock.release()
+        gc.collect()
+
+    elapsed = time.perf_counter() - start_time
+    print(
+        f"\t📤 API branch_next response: "
+        f"prefix_tokens={result.get('prefix_tokens')}, "
+        f"candidates={len(result.get('candidates', []))}, "
+        f"response_time={elapsed:.4f}s"
+    )
+    return {"success": True, **result}, 200

backend/api/client_activity.py

@@ -0,0 +1,60 @@
+from urllib.parse import unquote
+
+from backend.api.utils import request_has_valid_admin
+from backend.platform.access_log import log_request
+from backend.platform.online_presence import WINDOW_SEC, get_online_now, record_heartbeat
+from backend.platform.visit_stats import normalize_page_key, record_activity_report, record_gen_attr_opt_sec
+
+
+def _activity_response() -> dict:
+    return {"ok": True, "online_now": get_online_now(), "online_window_sec": WINDOW_SEC}
+
+
+def _sparse_page_activity_log_cum(cum: int) -> bool:
+    """无服务端状态：累计秒为 2、10、20（前 20s 内与前端档位一致）或 40、80、160…（40·2^k）时打访问日志。"""
+    if cum in (2, 10, 20):
+        return True
+    if cum < 40 or cum % 40:
+        return False
+    q = cum // 40
+    return q > 0 and (q & (q - 1)) == 0
+
+
+def client_activity_report(activity_body=None):
+    d = activity_body if isinstance(activity_body, dict) else {}
+    p = str(d.get("page_path") or "")[:512].strip()
+    try:
+        cum = int(d.get("total_active_sec"))
+        dlt = int(d.get("delta_active_sec"))
+        if not p or cum < 1 or dlt < 0:
+            return _activity_response()
+    except (TypeError, ValueError):
+        return _activity_response()
+    path_only = p.split("?", 1)[0].split("#", 1)[0].strip()
+    page_key = path_only.rstrip("/").split("/")[-1] or path_only
+    if not page_key:
+        return _activity_response()
+    if "?" in p:
+        qs = p.split("?", 1)[1].split("#", 1)[0]
+        log_path = f"{page_key}?{unquote(qs)}" if qs else page_key
+    else:
+        log_path = page_key
+
+    page_key = normalize_page_key(page_key)
+
+    if not request_has_valid_admin():
+        raw_os = d.get("client_os")
+        client_os = str(raw_os).strip() if raw_os is not None else None
+
+        record_heartbeat()
+        record_activity_report(page_key, dlt, cum, client_os)
+        if page_key == "causal_flow.html":
+            raw_opts = d.get("page_opts")
+            if isinstance(raw_opts, dict):
+                record_gen_attr_opt_sec(dlt, {k: bool(v) for k, v in raw_opts.items() if isinstance(k, str)})
+        if _sparse_page_activity_log_cum(cum):
+            log_request(
+                "📄 页面活跃",
+                f"path(sampled)={log_path!r} total_sec={cum} delta_sec={dlt}",
+            )
+    return _activity_response()

backend/api/demo.py

@@ -0,0 +1,174 @@
+"""Demo 文件管理 API"""
+from backend.demo.data_utils import save_demo_payload
+from backend.demo.demo_folder import (
+    list_demo_items,
+    move_demo_file,
+    rename_demo_file,
+    delete_demo_file,
+    move_folder,
+)
+from backend.api.utils import (
+    get_demo_directory,
+    handle_api_error,
+    handle_api_success,
+    require_admin,
+    validate_admin_token,
+)
+from backend.platform.access_log import log_check_admin
+
+
+def list_demos(path: str = ""):
+    """
+    扫描demo目录下的文件夹和文件，返回列表
+    支持指定路径参数，返回指定路径下的内容
+    文件名（去掉.json后缀）作为demo名称
+    支持中文文件名和路径
+    从data/demo目录读取（更专业的数据目录结构）
+    
+    Args:
+        path: 可选，指定要列出的路径，默认为根目录（空字符串）
+    """
+    demo_dir = get_demo_directory(create=False)
+    try:
+        result = list_demo_items(demo_dir, path)
+        # if not result.get("items"):
+        #     print(f"⚠️  路径 '{path}' 下没有内容: {demo_dir}")
+        # else:
+        #     items_count = len(result["items"])
+        #     folders_count = sum(1 for item in result["items"] if item["type"] == "folder")
+        #     files_count = sum(1 for item in result["items"] if item["type"] == "file")
+        #     print(f"✓ 路径 '{path}': {folders_count} 个文件夹, {files_count} 个文件 (共 {items_count} 项)")
+        return result
+    except Exception as e:
+        error_result = handle_api_error("Failed to scan demo directory", e)
+        return {"path": path, "items": []}
+
+
+@require_admin
+def save_demo(save_request):
+    """
+    保存demo文件到data/demo目录
+    请求格式: { name: string, data: AnalyzeResponse, path?: string, overwrite?: boolean }
+    path: 可选，保存路径，默认为根目录（"/"）
+    overwrite: 可选，是否覆盖已存在的文件，默认为False
+    """
+    name = save_request.get('name')
+    data = save_request.get('data')
+    path = save_request.get('path', '/')  # 默认为根目录
+    overwrite = save_request.get('overwrite', False)  # 默认为False
+    
+    if not name or not data:
+        return {
+            'success': False,
+            'message': 'Missing required parameters: name or data'
+        }
+    
+    try:
+        demo_dir = get_demo_directory(create=True)
+        result = save_demo_payload(demo_dir, name, data, path, overwrite)
+        if result.get('success'):
+            print(f"✓ Demo已保存: {demo_dir / result['file']}")
+        else:
+            print(f"❌ Save failed: {result.get('message')}")
+        return result
+    except Exception as e:
+        return handle_api_error('Save failed', e)
+
+
+@require_admin
+def delete_demo(delete_request):
+    """
+    将demo文件移动到deleted文件夹（软删除）
+    请求格式: { file: string }  # 文件名（包含.json后缀）
+    """
+    file = delete_request.get('file')
+    
+    if not file:
+        return {
+            'success': False,
+            'message': 'Missing required parameter: file'
+        }
+    
+    try:
+        demo_dir = get_demo_directory(create=False)
+        result = delete_demo_file(demo_dir, file)
+        return handle_api_success(result)
+    except Exception as e:
+        return handle_api_error('Delete failed', e)
+
+
+@require_admin
+def move_demo(move_request):
+    """
+    移动demo文件或文件夹
+    请求格式: { file: string, target_path: string } 或 { path: string, target_path: string }
+    """
+    file = move_request.get('file')
+    path = move_request.get('path')
+    target_path = move_request.get('target_path', '')
+    
+    if not target_path and target_path != '':
+        return {
+            'success': False,
+            'message': 'Missing required parameter: target_path'
+        }
+    
+    if not file and not path:
+        return {
+            'success': False,
+            'message': 'Missing required parameter: file or path'
+        }
+    
+    try:
+        demo_dir = get_demo_directory(create=False)
+        
+        if file:
+            # 移动文件
+            result = move_demo_file(demo_dir, file, target_path)
+        else:
+            # 移动文件夹
+            result = move_folder(demo_dir, path, target_path)
+        
+        return handle_api_success(result)
+    except Exception as e:
+        return handle_api_error('Move failed', e)
+
+
+@require_admin
+def rename_demo(rename_request):
+    """
+    重命名demo文件
+    请求格式: { file: string, new_name: string }
+    """
+    file = rename_request.get('file')
+    new_name = rename_request.get('new_name')
+    
+    if not file or not new_name:
+        return {
+            'success': False,
+            'message': 'Missing required parameter: file or new_name'
+        }
+    
+    try:
+        demo_dir = get_demo_directory(create=False)
+        result = rename_demo_file(demo_dir, file, new_name)
+        return handle_api_success(result)
+    except Exception as e:
+        return handle_api_error('Rename failed', e)
+
+
+def check_admin(check_request):
+    from flask import request
+
+    request_token = check_request.get('token') or request.headers.get('X-Admin-Token')
+    is_valid, error_message = validate_admin_token(request_token)
+    log_check_admin(is_valid, token=request_token)
+
+    if is_valid:
+        return {"success": True}
+    else:
+        return {
+            'success': False,
+            'message': error_message
+        }
+

backend/api/fetch_url.py

@@ -0,0 +1,221 @@
+"""URL 文本提取 API"""
+import json
+import re
+from urllib.parse import urlparse
+import trafilatura
+import requests
+from backend.api.utils import handle_api_error
+
+# 单次提取的最大字符数上限（防止异常大页面影响性能）
+MAX_EXTRACTED_TEXT_LENGTH = 20000
+
+
+def _is_valid_url(url: str) -> bool:
+    """验证 URL 格式"""
+    try:
+        result = urlparse(url)
+        return all([result.scheme in ['http', 'https'], result.netloc])
+    except Exception:
+        return False
+
+
+def _is_local_or_private(url: str) -> bool:
+    """检查是否为本地或私有网络地址（防止 SSRF 攻击）"""
+    try:
+        parsed = urlparse(url)
+        hostname = parsed.hostname
+        
+        if not hostname:
+            return True
+        
+        # 检查是否为 localhost
+        if hostname in ['localhost', '127.0.0.1', '::1']:
+            return True
+        
+        # 检查是否为私有 IP 地址
+        private_patterns = [
+            r'^10\.',  # 10.0.0.0/8
+            r'^172\.(1[6-9]|2[0-9]|3[0-1])\.',  # 172.16.0.0/12
+            r'^192\.168\.',  # 192.168.0.0/16
+            r'^169\.254\.',  # 169.254.0.0/16 (link-local)
+        ]
+        
+        for pattern in private_patterns:
+            if re.match(pattern, hostname):
+                return True
+        
+        return False
+    except Exception:
+        return True  # 解析失败时保守处理，拒绝访问
+
+
+def _format_article_text(metadata: dict) -> str:
+    """
+    将元数据和正文格式化为类似网页显示的纯文本
+    
+    Args:
+        metadata: trafilatura 提取的 JSON 数据（已解析为字典）
+    
+    Returns:
+        格式化后的文章文本
+    """
+    lines = []
+    
+    # 标题
+    if metadata.get('title'):
+        lines.append(metadata['title'])
+        lines.append('')
+    
+    # 元数据信息（无标签，直接显示内容）
+    meta_parts = []
+    if metadata.get('author'):
+        meta_parts.append(metadata['author'])
+    if metadata.get('date'):
+        meta_parts.append(metadata['date'])
+    # if metadata.get('hostname'):
+    #     meta_parts.append(metadata['hostname'])
+    if metadata.get('source-hostname'):
+        meta_parts.append(metadata['source-hostname'])
+    # if metadata.get('filedate'):
+    #     meta_parts.append(metadata['filedate'])
+
+    if meta_parts:
+        lines.append(' | '.join(meta_parts))
+        lines.append('')
+    
+    # 正文
+    if metadata.get('text'):
+        lines.append(metadata['text'])
+    
+    return '\n'.join(lines)
+
+
+def fetch_url(fetch_request):
+    """
+    从 URL 提取文本内容
+    
+    Args:
+        fetch_request: 包含 url 字段的字典
+    
+    Returns:
+        (响应字典, 状态码) 元组
+    """
+    url = fetch_request.get('url', '').strip()
+    
+    # 验证 URL
+    if not url:
+        return {
+            'success': False,
+            'message': '缺少 URL 参数，请提供 url 字段'
+        }, 400
+    
+    if not _is_valid_url(url):
+        return {
+            'success': False,
+            'message': f'无效的 URL 格式: {url}'
+        }, 400
+    
+    # 安全检查：防止 SSRF 攻击
+    if _is_local_or_private(url):
+        return {
+            'success': False,
+            'message': '不允许访问本地或私有网络地址'
+        }, 400
+    
+    # 提取文本和元数据
+    try:
+        from backend.platform.access_log import log_fetch_url
+        log_fetch_url(url)
+        
+        # 使用 requests 下载网页，设置浏览器 User-Agent 和请求头
+        headers = {
+            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+            'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8',
+            'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
+            'Accept-Encoding': 'gzip, deflate, br',
+            'Connection': 'keep-alive',
+            'Upgrade-Insecure-Requests': '1',
+        }
+        
+        # 下载网页内容（设置超时和请求头）
+        response = requests.get(url, headers=headers, timeout=10, allow_redirects=True)
+        response.raise_for_status()
+        
+        # 检查响应内容类型
+        content_type = response.headers.get('Content-Type', '').lower()
+        if 'text/html' not in content_type and 'text/xml' not in content_type:
+            return {
+                'success': False,
+                'message': f'不支持的内容类型: {content_type}，仅支持 HTML/XML 页面'
+            }, 400
+        
+        # 使用 trafilatura 提取结构化数据（包含元数据和正文）
+        result_json = trafilatura.extract(
+            response.text,
+            url=url,
+            with_metadata=True,
+            output_format='json'
+        )
+        
+        if not result_json:
+            print("⚠️ 无法提取页面内容")
+            return {
+                'success': False,
+                'message': '无法从网页中提取文本内容，可能不是文章页面或页面需要验证'
+            }, 400
+        
+        # 解析 JSON 数据
+        metadata = json.loads(result_json)
+        
+        # 检查是否有正文内容
+        if not metadata.get('text') or not metadata['text'].strip():
+            print("⚠️ 提取到元数据但无正文内容")
+            print("元数据:", json.dumps(metadata, ensure_ascii=False, indent=2))
+            return {
+                'success': False,
+                'message': '无法从网页中提取正文内容'
+            }, 400
+        
+        # 格式化文本（元数据 + 正文）
+        formatted_text = _format_article_text(metadata)
+        original_char_count = len(formatted_text)
+        
+        # 构建返回消息（如果截断了，添加提示）
+        message = None
+        # 检查并截断超长文本
+        if original_char_count > MAX_EXTRACTED_TEXT_LENGTH:
+            formatted_text = formatted_text[:MAX_EXTRACTED_TEXT_LENGTH]
+            message = f'内容较长，已截断为前 {MAX_EXTRACTED_TEXT_LENGTH} 字符（原始长度: {original_char_count} 字符）'
+        
+        char_count = len(formatted_text)
+        
+        # 打印提取结果
+        # print(formatted_text.split('\n')[:4])
+        # print(f"✓ 提取成功: {char_count} 字符" + (f" (截断前: {original_char_count} 字符)" if original_char_count > char_count else ""))
+        # 打印除正文外的metadata内容
+        metadata_less = metadata.copy()
+        metadata_less['raw_text'] = ''
+        metadata_less['text'] = ''
+        # print(json.dumps(metadata_less, ensure_ascii=False, indent=2))
+        
+        return {
+            'success': True,
+            'text': formatted_text,
+            'url': url,
+            'char_count': char_count,
+            'message': message
+        }, 200
+        
+    except requests.exceptions.Timeout:
+        return {
+            'success': False,
+            'message': '请求超时，请检查网络连接或稍后重试'
+        }, 400
+    except requests.exceptions.RequestException as e:
+        return {
+            'success': False,
+            'message': f'无法访问 URL: {str(e)}'
+        }, 400
+    except Exception as e:  # noqa: BLE001
+        error_response = handle_api_error('URL 文本提取失败', e)
+        return error_response, 500

backend/api/folder.py

@@ -0,0 +1,102 @@
+"""文件夹管理 API"""
+from backend.demo.demo_folder import (
+    get_all_folders,
+    move_folder,
+    rename_folder,
+    delete_folder,
+    create_folder,
+)
+from backend.api.utils import (
+    get_demo_directory,
+    handle_api_error,
+    handle_api_success,
+    require_admin,
+)
+
+
+def _move_folder_internal(demo_dir, path, target_path):
+    """内部函数：移动文件夹"""
+    return move_folder(demo_dir, path, target_path)
+
+
+@require_admin
+def rename_folder_api(rename_request):
+    """
+    重命名文件夹
+    请求格式: { path: string, new_name: string }
+    """
+    path = rename_request.get('path')
+    new_name = rename_request.get('new_name')
+    
+    if not path or not new_name:
+        return {
+            'success': False,
+            'message': 'Missing required parameter: path or new_name'
+        }
+    
+    try:
+        demo_dir = get_demo_directory(create=False)
+        result = rename_folder(demo_dir, path, new_name)
+        return handle_api_success(result)
+    except Exception as e:
+        return handle_api_error('Rename failed', e)
+
+
+@require_admin
+def delete_folder_api(delete_request):
+    """
+    删除文件夹（移动到.deleted目录）
+    请求格式: { path: string }
+    """
+    path = delete_request.get('path')
+    
+    if not path:
+        return {
+            'success': False,
+            'message': 'Missing required parameter: path'
+        }
+    
+    try:
+        demo_dir = get_demo_directory(create=False)
+        result = delete_folder(demo_dir, path)
+        return handle_api_success(result)
+    except Exception as e:
+        return handle_api_error('Delete failed', e)
+
+
+def list_all_folders():
+    """
+    获取所有文件夹列表（用于移动操作的选择器）
+    返回格式: { folders: string[] }
+    """
+    try:
+        demo_dir = get_demo_directory(create=False)
+        folders = get_all_folders(demo_dir)
+        return {'folders': folders}
+    except Exception as e:
+        handle_api_error("Failed to get folder list", e)
+        return {'folders': []}
+
+
+@require_admin
+def create_folder_api(create_request):
+    """
+    创建新文件夹
+    请求格式: { parent_path: string, folder_name: string }
+    """
+    parent_path = create_request.get('parent_path', '/')
+    folder_name = create_request.get('folder_name')
+    
+    if not folder_name:
+        return {
+            'success': False,
+            'message': 'Missing required parameter: folder_name'
+        }
+    
+    try:
+        demo_dir = get_demo_directory(create=False)
+        result = create_folder(demo_dir, parent_path, folder_name)
+        return handle_api_success(result)
+    except Exception as e:
+        return handle_api_error('Create failed', e)
+

backend/api/logit_lens.py

@@ -0,0 +1,104 @@
+"""Logit Lens API"""
+import gc
+import time
+
+from backend.models.model_manager import inference_lock
+from backend.platform.oom import exit_if_oom
+from backend.core.logit_lens import analyze_logit_lens
+from backend.api.analyze import LOCK_WAIT_TIMEOUT
+from backend.platform.access_log import get_client_ip, log_prediction_attribute_request
+from backend.platform.source_page import ALLOWED_SOURCE_PAGES, normalize_source_page
+
+
+def logit_lens(logit_lens_request):
+    context = logit_lens_request.get("context")
+    target_prediction = logit_lens_request.get("target_prediction")
+    target_token_id = logit_lens_request.get("target_token_id")
+    model = logit_lens_request.get("model")
+    source_page = logit_lens_request.get("source_page")
+    flow_id = logit_lens_request.get("flow_id")
+    flow_step = logit_lens_request.get("flow_step")
+
+    if context is None or context == "":
+        return {"success": False, "message": "Missing required field: context"}, 400
+    if not isinstance(context, str):
+        return {"success": False, "message": "context must be a string"}, 400
+    if target_prediction is not None and not isinstance(target_prediction, str):
+        return {"success": False, "message": "target_prediction must be a string"}, 400
+    if target_prediction == "":
+        return {"success": False, "message": "target_prediction must not be empty"}, 400
+    if target_token_id is not None and not isinstance(target_token_id, int):
+        return {"success": False, "message": "target_token_id must be an integer"}, 400
+    if target_token_id is not None and target_token_id < 0:
+        return {"success": False, "message": "target_token_id must be >= 0"}, 400
+    if target_prediction is not None and target_token_id is not None:
+        return {"success": False, "message": "target_prediction and target_token_id are mutually exclusive"}, 400
+
+    if model is None:
+        return {"success": False, "message": "Missing required field: model"}, 400
+    if model not in ("base", "instruct"):
+        return {"success": False, "message": 'model must be "base" or "instruct"'}, 400
+
+    if source_page is None or source_page == "":
+        return {"success": False, "message": "Missing required field: source_page"}, 400
+    normalized_source_page = normalize_source_page(source_page)
+    if normalized_source_page is None:
+        allowed = ", ".join(sorted(ALLOWED_SOURCE_PAGES))
+        return {"success": False, "message": f"source_page must be one of: {allowed}"}, 400
+    source_page = normalized_source_page
+
+    if flow_id is not None and not isinstance(flow_id, str):
+        return {"success": False, "message": "flow_id must be a string"}, 400
+    if flow_id == "":
+        return {"success": False, "message": "flow_id must not be empty"}, 400
+    if flow_step is not None and not isinstance(flow_step, int):
+        return {"success": False, "message": "flow_step must be an integer"}, 400
+    if flow_step is not None and flow_step < 0:
+        return {"success": False, "message": "flow_step must be >= 0"}, 400
+
+    is_causal_flow = source_page == "causal_flow"
+    if is_causal_flow:
+        if flow_id is None:
+            return {"success": False, "message": "Missing required field: flow_id for causal flow"}, 400
+        if flow_step is None:
+            return {"success": False, "message": "Missing required field: flow_step for causal flow"}, 400
+    elif flow_id is not None or flow_step is not None:
+        return {"success": False, "message": "flow_id/flow_step are only allowed when source_page is causal_flow"}, 400
+
+    client_ip = get_client_ip()
+    start_time = time.perf_counter()
+    request_id = log_prediction_attribute_request(
+        context=context,
+        target_prediction=target_prediction,
+        target_token_id=target_token_id,
+        model=model,
+        source_page=source_page,
+        flow_id=flow_id,
+        flow_step=flow_step,
+        client_ip=client_ip,
+    )
+
+    lock_acquired = inference_lock.acquire(timeout=LOCK_WAIT_TIMEOUT)
+    if not lock_acquired:
+        return {"success": False, "message": f"Queue wait exceeded {LOCK_WAIT_TIMEOUT} seconds; server is busy, please try again later."}, 503
+
+    try:
+        result = analyze_logit_lens(context, target_prediction, model=model, target_token_id=target_token_id)
+    except ValueError as e:
+        return {"success": False, "message": str(e)}, 400
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        exit_if_oom(e, defer_seconds=1)
+        return {"success": False, "message": str(e)}, 500
+    finally:
+        inference_lock.release()
+        gc.collect()
+
+    elapsed = time.perf_counter() - start_time
+    print(
+        f"\t📤 API logit_lens response: req_id={request_id}, "
+        f"target={result.get('target_token')!r}, n_layers={result.get('n_layers')}, "
+        f"response_time={elapsed:.4f}s"
+    )
+    return {"success": True, **result}, 200

backend/api/model_switch.py

@@ -0,0 +1,229 @@
+"""模型切换 API"""
+import gc
+import os
+from typing import Optional
+
+import torch
+from backend.models import REGISTERED_MODELS
+from backend.models.model_manager import project_registry
+from backend.platform.app_context import get_app_context
+from backend.api.utils import require_admin
+
+
+def get_available_models():
+    """获取所有可用的模型列表"""
+    return {
+        'success': True,
+        'models': list(REGISTERED_MODELS.keys())
+    }, 200
+
+
+def _get_device_type() -> str:
+    """获取当前设备类型"""
+    if torch.cuda.is_available():
+        return "cuda"
+    elif hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
+        return "mps"
+    else:
+        return "cpu"
+
+
+def _restore_env_vars(old_force_int8: Optional[str], old_force_bfloat16: Optional[str]) -> None:
+    """恢复环境变量配置"""
+    if old_force_int8 is not None:
+        os.environ['FORCE_INT8'] = old_force_int8
+    else:
+        os.environ.pop('FORCE_INT8', None)
+    
+    if old_force_bfloat16 is not None:
+        os.environ['CPU_FORCE_BFLOAT16'] = old_force_bfloat16
+    else:
+        os.environ.pop('CPU_FORCE_BFLOAT16', None)
+
+
+def get_current_model():
+    """获取当前使用的模型及量化配置"""
+    # 使用模块级上下文以获取持久化的模型状态
+    context = get_app_context(prefer_module_context=True)
+    device_type = _get_device_type()
+    
+    return {
+        'success': True,
+        'model': context.base_model_id,
+        'loading': context.model_loading,
+        'device_type': device_type,
+        'use_int8': os.environ.get('FORCE_INT8') == '1',
+        'use_bfloat16': os.environ.get('CPU_FORCE_BFLOAT16') == '1'
+    }, 200
+
+
+@require_admin
+def switch_model(switch_request):
+    """
+    切换模型（需要管理员权限）
+    
+    Args:
+        switch_request: 切换请求字典，包含：
+            - model: 目标模型名称
+            - use_int8: 是否使用 INT8 量化（可选）
+            - use_bfloat16: 是否使用 bfloat16（可选，仅CPU）
+    
+    Returns:
+        (响应字典, 状态码) 元组
+    """
+    if False:  # 原在线切换逻辑保留，不执行；恢复时请删除此守卫并测试
+        target_model = switch_request.get('model')
+        use_int8 = switch_request.get('use_int8', False)
+        use_bfloat16 = switch_request.get('use_bfloat16', False)
+
+        # 验证请求
+        if not target_model:
+            return {
+                'success': False,
+                'message': 'Missing model parameter'
+            }, 400
+
+        # 检查模型是否可用
+        if target_model not in REGISTERED_MODELS:
+            available_models = list(REGISTERED_MODELS.keys())
+            return {
+                'success': False,
+                'message': f'Model {target_model} does not exist. Available models: {", ".join(available_models)}'
+            }, 404
+
+        # 获取设备类型
+        device_type = _get_device_type()
+
+        # 验证量化参数与设备兼容性
+        if use_int8 and device_type == "mps":
+            return {
+                'success': False,
+                'message': 'INT8 quantization is not supported on MPS device'
+            }, 400
+
+        if use_bfloat16 and device_type != "cpu":
+            return {
+                'success': False,
+                'message': 'bfloat16 quantization is only supported on CPU device'
+            }, 400
+
+        if use_int8 and use_bfloat16:
+            return {
+                'success': False,
+                'message': 'Cannot enable both INT8 and bfloat16 quantization'
+            }, 400
+
+        # 使用模块级上下文以确保状态修改持久化（不会被后续请求重置）
+        context = get_app_context(prefer_module_context=True)
+        current_model = context.base_model_id
+
+        # 保存当前环境变量配置（用于回滚）
+        old_force_int8 = os.environ.get('FORCE_INT8')
+        old_force_bfloat16 = os.environ.get('CPU_FORCE_BFLOAT16')
+
+        # 检查是否已经是目标模型且量化配置相同
+        current_int8 = os.environ.get('FORCE_INT8') == '1'
+        current_bfloat16 = os.environ.get('CPU_FORCE_BFLOAT16') == '1'
+
+        if (current_model == target_model and
+                current_int8 == use_int8 and
+                current_bfloat16 == use_bfloat16):
+            return {
+                'success': True,
+                'message': f'Already using model {target_model} (same quantization configuration)',
+                'model': target_model
+            }, 200
+
+        # 检查模型是否正在加载中（初始加载或切换）
+        if context.model_loading:
+            return {
+                'success': False,
+                'message': 'Model is currently loading, please try again later'
+            }, 503
+
+        try:
+            # 标记开始加载
+            context.set_model_loading(True)
+            print(f"🔄 开始切换模型: {current_model} -> {target_model}")
+
+            # 设置新的量化环境变量
+            if use_int8:
+                os.environ['FORCE_INT8'] = '1'
+                print("   设置量化: INT8")
+            else:
+                os.environ.pop('FORCE_INT8', None)
+
+            if use_bfloat16:
+                os.environ['CPU_FORCE_BFLOAT16'] = '1'
+                print("   设置量化: bfloat16")
+            else:
+                os.environ.pop('CPU_FORCE_BFLOAT16', None)
+
+            # 卸载旧模型
+            if current_model and current_model in project_registry:
+                print(f"   卸载旧模型: {current_model}")
+                project_registry.unload(current_model)
+                gc.collect()
+                if device_type == "cuda":
+                    torch.cuda.empty_cache()
+                elif device_type == "mps":
+                    torch.mps.empty_cache()
+
+            # 加载新模型
+            print(f"   加载新模型: {target_model}")
+            project_registry.ensure_loaded(target_model)
+
+            # 更新当前模型
+            context.set_current_model(target_model)
+
+            print(f"✅ 模型切换成功: {target_model}")
+
+            return {
+                'success': True,
+                'message': f'Model switched to {target_model}',
+                'model': target_model
+            }, 200
+
+        except KeyError:
+            # 模型不存在（虽然前面已经检查过，但以防万一）
+            print(f"❌ 模型切换失败: 模型 {target_model} 未注册")
+            # 回滚：恢复旧模型名称和环境变量
+            context.set_current_model(current_model)
+            _restore_env_vars(old_force_int8, old_force_bfloat16)
+            return {
+                'success': False,
+                'message': f'Model {target_model} is not registered'
+            }, 404
+
+        except Exception as e:
+            # 加载失败，尝试回滚
+            print(f"❌ 模型切换失败: {e}")
+            print(f"   尝试回滚到旧模型: {current_model}")
+
+            try:
+                # 回滚：恢复环境变量和重新加载旧模型
+                _restore_env_vars(old_force_int8, old_force_bfloat16)
+                if current_model:
+                    project_registry.ensure_loaded(current_model)
+                    context.set_current_model(current_model)
+                    print(f"✅ 已回滚到旧模型: {current_model}")
+            except Exception as rollback_error:
+                print(f"⚠️  回滚失败: {rollback_error}")
+
+            return {
+                'success': False,
+                'message': f'Model switch failed: {str(e)}'
+            }, 500
+
+        finally:
+            # 无论成功还是失败，都要清除加载标志
+            context.set_model_loading(False)
+            gc.collect()
+
+    return (
+        {
+            'success': False,
+            'message': '在线模型切换已禁用，请通过命令行 --base_model / --instruct_model 指定后重启服务',
+        },
+        501,
+    )

backend/api/openai_completions.py

@@ -0,0 +1,571 @@
+"""OpenAI 兼容 /v1/completions：语义分析同款模型续写，其余响应字段固定。"""
+
+import gc
+import queue
+import threading
+import time
+import traceback
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from backend.models.model_manager import (
+    ModelSlot,
+    inference_lock,
+    get_base_model_display_name,
+    get_instruct_model_display_name,
+)
+from backend.core.prediction_attributor import slot_for_prediction_attr_model
+from backend.platform.oom import exit_if_oom, is_oom_error
+from backend.api.utils import request_has_valid_admin
+from backend.core.completion_generator import (
+    ModelContextLimitUnknownError,
+    PromptTooLongError,
+    apply_chat_template_for_completion,
+    compute_tool_append_suffix,
+    completion_cancel_requested,
+    completion_max_token_length,
+    generate_completion_text,
+    global_completion_stop_event,
+    inference_shutdown_event,
+)
+from backend.api.analyze import LOCK_WAIT_TIMEOUT, QueueTimeoutError
+from backend.api.sse_utils import (
+    SSEProgressReporter,
+    send_completion_delta_event,
+    send_error_event,
+    send_result_event,
+)
+from backend.platform.access_log import get_client_ip
+
+# 单次续写 SSE：从进入流式生成器起算的墙钟上限（含排队等推理锁 + 生成）。
+COMPLETION_WALL_CLOCK_TIMEOUT_SEC = 300.0
+
+
+def _log_cmpl_issue(request_id: int, msg: str) -> None:
+    """续写非正常结束时一行说明（与成功时的 ``_log_completion_finished`` 二选一）。"""
+    print(f"\t⚠️ openai_completions req_id={request_id}: {msg}")
+
+
+def _log_request(model: str, prompt: str, client_ip=None):
+    from backend.platform.access_log import log_openai_completions_request
+    return log_openai_completions_request(model, prompt, client_ip)
+
+
+def _model_display_name_for_slot(slot: ModelSlot) -> str:
+    if slot == ModelSlot.BASE:
+        return get_base_model_display_name()
+    return get_instruct_model_display_name()
+
+
+def _build_response(
+    completion_text: str,
+    finish_reason: str,
+    prompt_tokens: int,
+    completion_tokens: int,
+    bpe_strings: List[Dict[str, Any]],
+    *,
+    model_display: str,
+):
+    """OpenAICompletionsResponse：choices + usage；info_radar 为续写 token 级数据。"""
+    total = prompt_tokens + completion_tokens
+    return {
+        "id": "cmpl-stub-info-radar",
+        "object": "text_completion",
+        "created": int(time.time()),
+        "model": model_display,
+        "choices": [
+            {
+                "text": completion_text,
+                "index": 0,
+                "finish_reason": finish_reason,
+            }
+        ],
+        "usage": {
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "total_tokens": total,
+        },
+        "info_radar": {
+            "bpe_strings": bpe_strings,
+        },
+    }
+
+
+# 与 generate_completion_text 返回一致（末项 TTFT 秒；未生成时为 None）
+CompletionRunResult = Tuple[str, str, int, int, List[Dict[str, Any]], Optional[float]]
+
+
+def _completion_inference_after_lock(
+    prompt: str,
+    request_id: int,
+    lock_wait_time: float,
+    *,
+    slot: ModelSlot,
+    stream_delta: Optional[Callable[[str, bool], None]] = None,
+    max_tokens: Optional[int] = None,
+    bypass_site_context_limit: bool = False,
+) -> CompletionRunResult:
+    """
+    在已持有推理锁的上下文中执行续写（旧版非流式路径的持锁体内逻辑）。
+    流式可传 stream_delta；中止由 ``completion_cancel_requested()`` 统一判断。
+    """
+    from backend.platform.access_log import log_openai_completions_start
+
+    log_openai_completions_start(request_id, lock_wait_time)
+    return generate_completion_text(
+        prompt,
+        stream_delta=stream_delta,
+        max_tokens=max_tokens,
+        bypass_site_context_limit=bypass_site_context_limit,
+        slot=slot,
+    )
+
+
+def _log_completion_finished(
+    request_id: int,
+    prompt_tokens: int,
+    completion_tokens: int,
+    elapsed: float,
+    ttft_s: Optional[float],
+) -> None:
+    """旧非流式分支在返回 JSON 前、流式在发出末条 result 前的同一行日志。
+
+    prompt tokens/s = prompt_tokens / TTFT；generate tokens/s = completion_tokens / (elapsed − TTFT)。
+    ``elapsed`` 为 SSE 起点至结束；与 TTFT 计时原点不完全一致时，吞吐率为近似值。
+    无 TTFT（``ttft_s`` 为 ``None``）时不输出时间与吞吐字段。
+    """
+    if ttft_s is None:
+        tps_part = ""
+    else:
+        decode_s = elapsed - ttft_s
+        prompt_time_s = f"{ttft_s:.4f}" if ttft_s > 0 else "n/a"
+        gen_time_s = f"{decode_s:.4f}" if decode_s > 0 else "n/a"
+        prompt_part = f"{prompt_tokens / ttft_s:.2f}" if ttft_s > 0 else "n/a"
+        gen_part = (
+            f"{completion_tokens / decode_s:.2f}"
+            if completion_tokens and decode_s > 0
+            else "n/a"
+        )
+        tps_part = (
+            f", time= {prompt_time_s} / {gen_time_s}s, "
+            f"tokens/s= {prompt_part} / {gen_part}"
+        )
+    print(
+        f"\t📤 API openai_completions response: req_id={request_id}, "
+        f"prompt/generate tokens= {prompt_tokens} / {completion_tokens}, "
+        f"{tps_part}"
+    )
+
+
+def _generate_completion_events(
+    prompt: str,
+    request_id: int,
+    *,
+    slot: ModelSlot,
+    model_display: str,
+    max_tokens: Optional[int] = None,
+    bypass_site_context_limit: bool = False,
+):
+    global_completion_stop_event.clear()
+    q: queue.Queue = queue.Queue()
+    start_time = time.perf_counter()
+
+    def run():
+        try:
+            lock_wait_start = time.perf_counter()
+            lock_acquired = inference_lock.acquire(timeout=LOCK_WAIT_TIMEOUT)
+            if not lock_acquired:
+                q.put(("error", QueueTimeoutError(
+                    f"排队等待超过 {LOCK_WAIT_TIMEOUT} 秒，服务繁忙，请稍后重试"
+                )))
+                return
+            lock_wait_time = time.perf_counter() - lock_wait_start
+            try:
+                def stream_delta(text: str, stream_end: bool) -> None:
+                    if completion_cancel_requested():
+                        return
+                    q.put(("delta", text, stream_end))
+
+                result = _completion_inference_after_lock(
+                    prompt,
+                    request_id,
+                    lock_wait_time,
+                    slot=slot,
+                    stream_delta=stream_delta,
+                    max_tokens=max_tokens,
+                    bypass_site_context_limit=bypass_site_context_limit,
+                )
+            finally:
+                inference_lock.release()
+                gc.collect()
+            q.put(("result", result))
+        except Exception as e:
+            q.put(("error", e))
+
+    worker = threading.Thread(target=run, daemon=True)
+    worker.start()
+
+    wall_clock_timed_out = False
+
+    # 墙钟超时与用户 Stop 同路：置位 global_completion_stop_event，等 worker 末条 result（abort）。
+    # 正常路径由 completion_cancel_requested + StoppingCriteria 结束 generate；排队仅 LOCK_WAIT_TIMEOUT。
+    # 仅在与 Stop 相同的推理僵死（如 CUDA 挂死）时 SSE 可能一直等 result，旧 504 即时断开亦无法回收 worker。
+    try:
+        while True:
+            elapsed = time.perf_counter() - start_time
+            if (
+                not wall_clock_timed_out
+                and elapsed >= COMPLETION_WALL_CLOCK_TIMEOUT_SEC
+            ):
+                global_completion_stop_event.set()
+                wall_clock_timed_out = True
+                _log_cmpl_issue(
+                    request_id,
+                    f"墙钟超时 {elapsed:.1f}s / 上限 {COMPLETION_WALL_CLOCK_TIMEOUT_SEC:.0f}s",
+                )
+            try:
+                item = q.get(timeout=0.1)
+            except queue.Empty:
+                continue
+            kind = item[0]
+            if kind == "delta":
+                _, text, stream_end = item
+                if text or stream_end:
+                    yield send_completion_delta_event(text, stream_end)
+            elif kind == "result":
+                (
+                    _completion_text,
+                    finish_reason,
+                    prompt_tokens,
+                    completion_tokens,
+                    bpe_strings,
+                    ttft_s,
+                ) = item[1]
+                elapsed = time.perf_counter() - start_time
+                if global_completion_stop_event.is_set() or inference_shutdown_event.is_set():
+                    finish_reason = "abort"
+                if inference_shutdown_event.is_set():
+                    _log_cmpl_issue(
+                        request_id,
+                        f"进程终止，续写中止 elapsed={elapsed:.2f}s "
+                        f"tokens={prompt_tokens}/{completion_tokens}",
+                    )
+                elif global_completion_stop_event.is_set():
+                    stop_label = "墙钟超时" if wall_clock_timed_out else "用户 Stop"
+                    _log_cmpl_issue(
+                        request_id,
+                        f"{stop_label}，续写中止 elapsed={elapsed:.2f}s "
+                        f"tokens={prompt_tokens}/{completion_tokens}",
+                    )
+                else:
+                    _log_completion_finished(
+                        request_id,
+                        prompt_tokens,
+                        completion_tokens,
+                        elapsed,
+                        ttft_s,
+                    )
+                yield send_result_event(
+                    _build_response(
+                        _completion_text,
+                        finish_reason,
+                        prompt_tokens,
+                        completion_tokens,
+                        bpe_strings,
+                        model_display=model_display,
+                    )
+                )
+                return
+            elif kind == "error":
+                err = item[1]
+                if isinstance(err, (PromptTooLongError, ModelContextLimitUnknownError)):
+                    _log_cmpl_issue(request_id, str(err))
+                    yield send_error_event(str(err), 400)
+                elif isinstance(err, QueueTimeoutError):
+                    _log_cmpl_issue(request_id, f"排队超时: {err}")
+                    yield send_error_event(str(err), 503)
+                else:
+                    exit_if_oom(err, defer_seconds=1)
+                    if is_oom_error(err):
+                        yield send_error_event(str(err), 500)
+                        return
+                    _log_cmpl_issue(
+                        request_id,
+                        "".join(
+                            traceback.format_exception(
+                                type(err), err, err.__traceback__
+                            )
+                        ).strip(),
+                    )
+                    yield send_error_event(str(err), 500)
+                return
+    finally:
+        gc.collect()
+
+
+def _completions_sse_response(
+    prompt: str,
+    request_id: int,
+    *,
+    slot: ModelSlot,
+    model_display: str,
+    max_tokens: Optional[int] = None,
+    bypass_site_context_limit: bool = False,
+):
+    return SSEProgressReporter(
+        lambda: _generate_completion_events(
+            prompt,
+            request_id,
+            slot=slot,
+            model_display=model_display,
+            max_tokens=max_tokens,
+            bypass_site_context_limit=bypass_site_context_limit,
+        )
+    ).create_response()
+
+
+def completions_stop():
+    """
+    单用户串行：置位全局停止标志，使当前续写在 generate 与 SSE 回调中尽快结束。
+    无需 body；新一次 POST /v1/completions 时会在流式生成器入口清除该标志。
+    """
+    global_completion_stop_event.set()
+    return {"ok": True}, 200
+
+
+def _parse_chat_messages_from_prompt_request(
+    body: Dict[str, Any],
+) -> Tuple[Optional[List[Dict[str, Any]]], Optional[Dict[str, Any]]]:
+    """从 completions/prompt 请求体解析 messages。返回 (messages, error_response)。"""
+    raw_messages = body.get("messages")
+    if raw_messages is None:
+        return None, {"success": False, "message": "缺少 messages 字段"}
+    if not isinstance(raw_messages, list) or len(raw_messages) == 0:
+        return None, {"success": False, "message": "messages 须为非空数组"}
+    messages: List[Dict[str, Any]] = []
+    for i, item in enumerate(raw_messages):
+        if not isinstance(item, dict):
+            return None, {"success": False, "message": f"messages[{i}] 须为对象"}
+        role = item.get("role")
+        if role not in ("system", "user", "assistant", "tool"):
+            return None, {
+                "success": False,
+                "message": f"messages[{i}].role 无效: {role!r}",
+            }
+        content = item.get("content")
+        if not isinstance(content, str):
+            return None, {
+                "success": False,
+                "message": f"messages[{i}].content 须为字符串",
+            }
+        msg: Dict[str, Any] = {"role": role, "content": content}
+        if role == "tool":
+            name = item.get("name")
+            if not isinstance(name, str) or not name:
+                return None, {
+                    "success": False,
+                    "message": f"messages[{i}].name 在 role=tool 时必填",
+                }
+            msg["name"] = name
+        messages.append(msg)
+    return messages, None
+
+
+def _parse_tools_from_prompt_request(
+    body: Dict[str, Any],
+) -> Tuple[Optional[List[Dict[str, Any]]], Optional[Dict[str, Any]]]:
+    """解析 tools 数组；``enable_tool_calling`` 已废弃，须显式传 tools。"""
+    tools_raw = body.get("tools")
+    if tools_raw is None:
+        enable_tool_calling_raw = body.get("enable_tool_calling")
+        if enable_tool_calling_raw is True:
+            return None, {
+                "success": False,
+                "message": "enable_tool_calling 已废弃，请传 tools 数组",
+            }
+        return None, None
+
+    if not isinstance(tools_raw, list):
+        return None, {"success": False, "message": "tools 须为数组"}
+    return tools_raw, None
+
+
+def completions_prompt(completions_prompt_request):
+    """
+    将 messages 套用 chat template，返回实际送入续写接口的完整 prompt 字符串（JSON）。
+
+    Args:
+        completions_prompt_request: 含 model、messages，见 server_openai_definitions.yaml
+
+    Returns:
+        (dict with prompt_used, 200) 或校验/过长错误
+    """
+    if not isinstance(completions_prompt_request, dict):
+        completions_prompt_request = {}
+    model = completions_prompt_request.get("model")
+
+    if not model:
+        return {"success": False, "message": "缺少 model 字段"}, 400
+
+    messages, msg_err = _parse_chat_messages_from_prompt_request(completions_prompt_request)
+    if msg_err is not None:
+        return msg_err, 400
+
+    tools, tools_err = _parse_tools_from_prompt_request(completions_prompt_request)
+    if tools_err is not None:
+        return tools_err, 400
+
+    enable_thinking_raw = completions_prompt_request.get("enable_thinking")
+    if enable_thinking_raw is None:
+        enable_thinking = False
+    elif not isinstance(enable_thinking_raw, bool):
+        return {"success": False, "message": "enable_thinking 必须为布尔值"}, 400
+    else:
+        enable_thinking = enable_thinking_raw
+
+    client_ip = get_client_ip()
+    from backend.platform.access_log import log_openai_completions_prompt_request
+
+    log_openai_completions_prompt_request(
+        model,
+        messages=messages,
+        enable_thinking=enable_thinking,
+        tools_count=len(tools) if tools else 0,
+        client_ip=client_ip,
+    )
+
+    try:
+        slot = slot_for_prediction_attr_model(model)
+    except ValueError as e:
+        return {"success": False, "message": str(e)}, 400
+
+    try:
+        prompt_used = apply_chat_template_for_completion(
+            messages,
+            slot=slot,
+            enable_thinking=enable_thinking,
+            tools=tools,
+        )
+    except PromptTooLongError as e:
+        return {"success": False, "message": str(e)}, 400
+
+    return {"prompt_used": prompt_used}, 200
+
+
+def completions_prompt_incremental(completions_prompt_incremental_request):
+    """
+    计算多轮 wire 模式下 tool response 的增量后缀（incremental_suffix）。
+
+    wire 在模型输出 O_n（含 <|im_end|>）后，需追加本函数返回的字符串，
+    以构成下一轮生成的完整输入。suffix 仅取决于 tool_content 和 enable_thinking，
+    与前序历史内容无关。
+
+    Args:
+        completions_prompt_incremental_request: 含 model、tool_content，见 server_openai_definitions.yaml
+
+    Returns:
+        (dict with incremental_suffix, 200) 或校验错误
+    """
+    if not isinstance(completions_prompt_incremental_request, dict):
+        completions_prompt_incremental_request = {}
+    model = completions_prompt_incremental_request.get("model")
+
+    if not model:
+        return {"success": False, "message": "缺少 model 字段"}, 400
+
+    tool_content = completions_prompt_incremental_request.get("tool_content")
+    if not isinstance(tool_content, str):
+        return {"success": False, "message": "tool_content 须为字符串"}, 400
+
+    tool_name = completions_prompt_incremental_request.get("tool_name")
+    if tool_name is not None and not isinstance(tool_name, str):
+        return {"success": False, "message": "tool_name 须为字符串"}, 400
+
+    enable_thinking_raw = completions_prompt_incremental_request.get("enable_thinking")
+    if enable_thinking_raw is None:
+        enable_thinking = False
+    elif not isinstance(enable_thinking_raw, bool):
+        return {"success": False, "message": "enable_thinking 必须为布尔值"}, 400
+    else:
+        enable_thinking = enable_thinking_raw
+
+    try:
+        slot = slot_for_prediction_attr_model(model)
+    except ValueError as e:
+        return {"success": False, "message": str(e)}, 400
+
+    try:
+        suffix = compute_tool_append_suffix(
+            tool_content,
+            enable_thinking=enable_thinking,
+            tool_name=tool_name or None,
+            slot=slot,
+        )
+    except RuntimeError as e:
+        return {"success": False, "message": str(e)}, 500
+
+    return {"incremental_suffix": suffix}, 200
+
+
+def completions(completions_request):
+    """
+    文本补写：与 analyze_semantic 共用推理锁与 semantic 模型；响应恒为 text/event-stream（SSE）。
+    ``prompt`` 须为已确定的完整模型输入（需 chat template 时请先调 POST /v1/completions/prompt）。
+
+    Args:
+        completions_request: 含 model、prompt 等，见 server_openai_definitions.yaml
+
+    Returns:
+        SSE Response；校验失败时 (错误体, 400/503/500)
+    """
+    if not isinstance(completions_request, dict):
+        completions_request = {}
+    model = completions_request.get("model")
+    prompt = completions_request.get("prompt")
+
+    if not model:
+        return {"success": False, "message": "缺少 model 字段"}, 400
+    if prompt is None:
+        return {"success": False, "message": "缺少 prompt 字段"}, 400
+    if not isinstance(prompt, str):
+        return {"success": False, "message": "prompt 必须为字符串"}, 400
+
+    max_tokens_raw = completions_request.get("max_tokens")
+    max_tokens: Optional[int]
+    if max_tokens_raw is None:
+        max_tokens = None
+    elif type(max_tokens_raw) is not int:
+        return {"success": False, "message": "max_tokens 须为正整数"}, 400
+    elif max_tokens_raw <= 0:
+        return {"success": False, "message": "max_tokens 须 > 0"}, 400
+    else:
+        max_tokens = max_tokens_raw
+
+    bypass_site = request_has_valid_admin() and max_tokens is not None
+    if (
+        not bypass_site
+        and max_tokens is not None
+        and max_tokens > completion_max_token_length
+    ):
+        return {
+            "success": False,
+            "message": (
+                f"max_tokens 不得超过续写上下文上限 {completion_max_token_length}"
+            ),
+        }, 400
+
+    try:
+        slot = slot_for_prediction_attr_model(model)
+    except ValueError as e:
+        return {"success": False, "message": str(e)}, 400
+
+    client_ip = get_client_ip()
+    request_id = _log_request(model, prompt, client_ip)
+
+    return _completions_sse_response(
+        prompt,
+        request_id,
+        slot=slot,
+        model_display=_model_display_name_for_slot(slot),
+        max_tokens=max_tokens,
+        bypass_site_context_limit=bypass_site,
+    )

backend/api/prediction_attribute.py

@@ -0,0 +1,151 @@
+"""预测归因 API"""
+import gc
+import time
+
+from backend.models.model_manager import inference_lock
+from backend.platform.oom import exit_if_oom
+from backend.core.prediction_attributor import analyze_prediction_attribution
+from backend.api.analyze import LOCK_WAIT_TIMEOUT
+from backend.platform.access_log import get_client_ip, log_prediction_attribute_request
+from backend.platform.source_page import ALLOWED_SOURCE_PAGES, normalize_source_page
+
+
+def prediction_attribute(attribution_request):
+    """
+    对上下文文本的下一 token 预测做归因分析。
+
+    Args:
+        attribution_request: 须含 ``context``、``model``。归因目标二选一：
+            省略 ``target_prediction`` 且省略 ``target_token_id`` 时为 top-1；
+            或传非空 ``target_prediction``（字符串首 token）；
+            或传 ``target_token_id``（非负整数词表 id）；二者不可同时出现。
+
+    Returns:
+        (响应字典, 状态码) 元组
+    """
+    context = attribution_request.get("context")
+    target_prediction = attribution_request.get("target_prediction")
+    target_token_id = attribution_request.get("target_token_id")
+    model = attribution_request.get("model")
+    source_page = attribution_request.get("source_page")
+    flow_id = attribution_request.get("flow_id")
+    flow_step = attribution_request.get("flow_step")
+
+    if context is None:
+        return {"success": False, "message": "Missing required field: context"}, 400
+    if not isinstance(context, str):
+        return {"success": False, "message": "context must be a string"}, 400
+    if context == "":
+        return {"success": False, "message": "Missing required field: context"}, 400
+
+    if target_prediction is not None and not isinstance(target_prediction, str):
+        return {"success": False, "message": "target_prediction must be a string"}, 400
+    if target_prediction == "":
+        return {"success": False, "message": "target_prediction must not be empty"}, 400
+    if target_token_id is not None and not isinstance(target_token_id, int):
+        return {"success": False, "message": "target_token_id must be an integer"}, 400
+    if target_token_id is not None and target_token_id < 0:
+        return {"success": False, "message": "target_token_id must be >= 0"}, 400
+    if target_prediction is not None and target_token_id is not None:
+        return {"success": False, "message": "target_prediction and target_token_id are mutually exclusive"}, 400
+
+    if model is None:
+        return {"success": False, "message": "Missing required field: model"}, 400
+    if not isinstance(model, str):
+        return {"success": False, "message": "model must be a string"}, 400
+    if model not in ("base", "instruct"):
+        return {"success": False, "message": 'model must be "base" or "instruct"'}, 400
+
+    if source_page is None:
+        return {"success": False, "message": "Missing required field: source_page"}, 400
+    if not isinstance(source_page, str):
+        return {"success": False, "message": "source_page must be a string"}, 400
+    if source_page == "":
+        return {"success": False, "message": "source_page must not be empty"}, 400
+    normalized_source_page = normalize_source_page(source_page)
+    if normalized_source_page is None:
+        allowed = ", ".join(sorted(ALLOWED_SOURCE_PAGES))
+        return {
+            "success": False,
+            "message": f"source_page must be one of: {allowed} (legacy *.html and gen_attribute accepted)",
+        }, 400
+    source_page = normalized_source_page
+
+    if flow_id is not None and not isinstance(flow_id, str):
+        return {"success": False, "message": "flow_id must be a string"}, 400
+    if flow_id == "":
+        return {"success": False, "message": "flow_id must not be empty"}, 400
+    if flow_step is not None and not isinstance(flow_step, int):
+        return {"success": False, "message": "flow_step must be an integer"}, 400
+    if flow_step is not None and flow_step < 0:
+        return {"success": False, "message": "flow_step must be >= 0"}, 400
+
+    is_causal_flow = source_page == "causal_flow"
+    if is_causal_flow:
+        if flow_id is None:
+            return {"success": False, "message": "Missing required field: flow_id for causal flow"}, 400
+        if flow_step is None:
+            return {"success": False, "message": "Missing required field: flow_step for causal flow"}, 400
+    elif flow_id is not None or flow_step is not None:
+        return {
+            "success": False,
+            "message": "flow_id/flow_step are only allowed when source_page is causal_flow",
+        }, 400
+
+    client_ip = get_client_ip()
+    start_time = time.perf_counter()
+    request_id = log_prediction_attribute_request(
+        context=context,
+        target_prediction=target_prediction,
+        target_token_id=target_token_id,
+        model=model,
+        source_page=source_page,
+        flow_id=flow_id,
+        flow_step=flow_step,
+        client_ip=client_ip,
+    )
+
+    lock_acquired = inference_lock.acquire(timeout=LOCK_WAIT_TIMEOUT)
+    if not lock_acquired:
+        return {
+            "success": False,
+            "message": (
+                f"Queue wait exceeded {LOCK_WAIT_TIMEOUT} seconds; "
+                "server is busy, please try again later."
+            ),
+        }, 503
+
+    try:
+        result = analyze_prediction_attribution(
+            context,
+            target_prediction,
+            model=model,
+            target_token_id=target_token_id,
+        )
+    except ValueError as e:
+        return {"success": False, "message": str(e)}, 400
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        exit_if_oom(e, defer_seconds=1)
+        return {"success": False, "message": str(e)}, 500
+    finally:
+        inference_lock.release()
+        gc.collect()
+
+    elapsed = time.perf_counter() - start_time
+    tokens = len(result.get("token_attribution", []))
+    target_token = result.get("target_token")
+    if flow_id is None:
+        print(
+            f"\t📤 API prediction_attribute response: req_id={request_id}, "
+            f"target={target_token!r}, tokens={tokens}, response_time={elapsed:.4f}s"
+        )
+    else:
+        print(
+            f"\t📤 API prediction_attribute response: req_id={request_id}, "
+            f"flow_id={flow_id!r}, flow_step={flow_step}, "
+            f"target={target_token!r}, tokens={tokens}, response_time={elapsed:.4f}s"
+        )
+
+    return {"success": True, **result}, 200

backend/api/sse_utils.py

@@ -0,0 +1,181 @@
+"""Server-Sent Events (SSE) 工具模块"""
+import json
+import queue
+import time
+from typing import Callable, Generator, Optional, Tuple
+from flask import Response
+
+
+class SSEProgressReporter:
+    """SSE进度报告器"""
+    
+    def __init__(self, generator_func: Callable):
+        """
+        初始化SSE进度报告器
+        
+        Args:
+            generator_func: 生成器函数，用于生成SSE事件
+        """
+        self.generator_func = generator_func
+    
+    def generate(self):
+        """生成SSE事件流"""
+        try:
+            for event in self.generator_func():
+                yield event
+        except Exception as e:
+            # 发送错误事件
+            error_data = {
+                'type': 'error',
+                'message': str(e)
+            }
+            yield f"data: {json.dumps(error_data)}\n\n"
+    
+    def create_response(self) -> Response:
+        """创建SSE响应"""
+        return Response(
+            self.generate(),
+            mimetype='text/event-stream',
+            headers={
+                'Cache-Control': 'no-cache',
+                'X-Accel-Buffering': 'no',  # 禁用nginx缓冲
+                'Connection': 'keep-alive'
+            }
+        )
+
+
+def send_progress_event(step: int, total_steps: int, stage: str, percentage: Optional[int] = None, message: Optional[str] = None) -> str:
+    """
+    生成SSE进度事件
+    
+    Args:
+        step: 当前步骤 (1-based)
+        total_steps: 总步骤数
+        stage: 阶段名称 (encoding, inference, processing)
+        percentage: 可选的进度百分比 (0-100)，仅在需要显示百分比的阶段提供
+        message: 可选的进度消息
+    
+    Returns:
+        SSE格式的事件字符串
+    """
+    data = {
+        'type': 'progress',
+        'step': step,
+        'total_steps': total_steps,
+        'stage': stage
+    }
+    if percentage is not None:
+        data['percentage'] = percentage
+    if message:
+        data['message'] = message
+    return f"data: {json.dumps(data)}\n\n"
+
+
+def send_result_event(result: dict) -> str:
+    """
+    生成SSE结果事件
+    
+    Args:
+        result: 分析结果字典
+    
+    Returns:
+        SSE格式的事件字符串
+    """
+    data = {
+        'type': 'result',
+        'data': result
+    }
+    return f"data: {json.dumps(data)}\n\n"
+
+
+def send_completion_delta_event(text: str, stream_end: bool) -> str:
+    """续写流式：与 analyze 的 progress/result 并列，type=delta。"""
+    data = {
+        "type": "delta",
+        "text": text,
+    }
+    if stream_end:
+        data["stream_end"] = True
+    return f"data: {json.dumps(data)}\n\n"
+
+
+def send_prompt_used_event(prompt_used: str) -> str:
+    """续写流式：在首条 delta 之前下发实际送入模型的 prompt 原文。"""
+    data = {
+        "type": "prompt_used",
+        "prompt_used": prompt_used,
+    }
+    return f"data: {json.dumps(data)}\n\n"
+
+
+def send_error_event(message: str, status_code: Optional[int] = None) -> str:
+    """
+    生成SSE错误事件
+
+    Args:
+        message: 错误消息
+        status_code: 可选 HTTP 状态码，供非流式封装解析
+
+    Returns:
+        SSE格式的事件字符串
+    """
+    data = {'type': 'error', 'message': message}
+    if status_code is not None:
+        data['status_code'] = status_code
+    return f"data: {json.dumps(data)}\n\n"
+
+
+def consume_progress_queue(
+    progress_queue: queue.Queue,
+    analysis_done,
+    start_time: float,
+    timeout_seconds: float,
+    timeout_label: str = "分析",
+) -> Generator[Tuple[str, str], None, None]:
+    """
+    消费进度队列，yield (kind, event_str)。
+    kind: 'progress' | 'timeout' | 'done'
+    event_str: SSE 格式字符串（timeout 时含错误信息，done 时为空）
+    """
+    done_received = False
+    last_progress_info = None
+
+    while True:
+        elapsed = time.perf_counter() - start_time
+        if elapsed >= timeout_seconds:
+            progress_str = f" | {last_progress_info}" if last_progress_info else ""
+            print(f"⏱️ {timeout_label}超时: 处理时长 {elapsed:.2f}s 超过限制 {timeout_seconds}s，已放弃{progress_str}")
+            yield ('timeout', send_error_event(f"分析超时：处理时长超过 {timeout_seconds} 秒限制，已放弃"))
+            return
+
+        try:
+            event_data = progress_queue.get(timeout=0.1)
+            event_type = event_data[0]
+            if event_type == 'progress':
+                _, step, total_steps, stage, percentage = event_data
+                if total_steps > 0:
+                    last_progress_info = f"step={step}/{total_steps}"
+                else:
+                    last_progress_info = f"step={step}"
+                if stage:
+                    last_progress_info += f" stage={stage}"
+                if percentage is not None:
+                    last_progress_info += f" {percentage}%"
+                yield ('progress', send_progress_event(step, total_steps, stage, percentage))
+            elif event_type == 'done':
+                done_received = True
+                while not progress_queue.empty():
+                    try:
+                        remaining = progress_queue.get_nowait()
+                        if remaining[0] == 'progress':
+                            _, step, total_steps, stage, percentage = remaining
+                            yield ('progress', send_progress_event(step, total_steps, stage, percentage))
+                    except queue.Empty:
+                        break
+                yield ('done', '')
+                return
+        except queue.Empty:
+            if analysis_done.is_set() and done_received:
+                yield ('done', '')
+                return
+

backend/api/static.py

@@ -0,0 +1,67 @@
+"""静态文件路由"""
+import mimetypes
+from pathlib import Path
+from urllib.parse import unquote
+
+from flask import Response, redirect, abort, request
+from werkzeug.utils import safe_join
+
+from backend.platform.access_log import log_cached_demo, log_json_demo, log_page_load
+
+
+def _read_static_file(directory: str, path: str) -> Response:
+    """读取静态文件并返回 Response，避免 send_from_directory 在 ASGI/a2wsgi 下
+    流式传输导致的 Content-Length 不匹配（RuntimeError: Response content shorter than Content-Length）。
+    """
+    base = Path(directory).resolve()
+    safe_path = safe_join(str(base), path)
+    if safe_path is None:
+        abort(404)
+    full_path = Path(safe_path)
+    if not full_path.is_file() or not str(full_path.resolve()).startswith(str(base)):
+        abort(404)
+    content = full_path.read_bytes()
+    mimetype, _ = mimetypes.guess_type(path)
+    mimetype = mimetype or "application/octet-stream"
+    return Response(content, mimetype=mimetype, headers={"Content-Length": str(len(content))})
+
+
+def register_static_routes(app):
+    """注册静态文件路由"""
+    
+    @app.route('/')
+    def redir():
+        target = 'client/index.html'
+        if request.query_string:
+            target += '?' + request.query_string.decode()
+        return redirect(target)
+
+    @app.route('/client/<path:path>')
+    def send_static(path):
+        """serves all files from ./client/dist/ to ``/client/<path:path>``"""
+        if path == 'gen_attribute.html':
+            target = 'causal_flow.html'
+            if request.query_string:
+                target += '?' + request.query_string.decode()
+            return redirect(f'/client/{target}', code=301)
+        if path.endswith('.html'):
+            log_page_load(path)
+        if path.endswith('.json'):
+            log_cached_demo(path)
+        return _read_static_file('client/dist', path)
+
+    @app.route('/demo/<path:path>')
+    def send_demo(path):
+        """serves all demo files from the demo dir to ``/demo/<path:path>``"""
+        from backend.platform.app_context import get_data_dir
+        data_dir = get_data_dir()
+        log_json_demo(path)
+        try:
+            decoded_path = unquote(path)
+            return _read_static_file(str(data_dir), decoded_path)
+        except Exception:
+            try:
+                return _read_static_file(str(data_dir), path)
+            except Exception:
+                abort(404)
+