analyze-with-file

使用文件进行分析

通过有记录的讨论流程开展交互式协作分析。记录理解的演进过程，促进多轮问答，并结合行内搜索和外部研究进行深入探索。

核心流程：主题 → 探索 → 讨论 → 优化 → 总结 → 下一步

自动模式（-y）：自动确认探索决策，采用推荐角度，跳过交互式范围界定。

配置

标志	默认值	描述
-y, --yes	false	自动确认所有决策
--continue	false	继续现有会话
--depth	standard	quick / standard / deep

会话 ID：ANL-{YYYY-MM-DD}-{slug}

• slug：topic.toLowerCase() → 保留 [a-z0-9\u4e00-\u9fa5]，其余字符替换为 -，最多 40 个字符
• 日期：UTC+8 时区的 YYYY-MM-DD
• 自动检测继续模式：会话文件夹中存在 discussion.md → 继续模式

产物

{projectRoot}/.workflow/.analysis/ANL-{date}-{slug}/
├── discussion.md              # Single source of truth: rounds, decisions, conclusions, synthesis
├── state.json                 # Session state: config, confidence, quality tracking
├── exploration-codebase.json  # Codebase exploration: files, patterns, constraints
├── research.json              # External research: best practices, pitfalls, sources
└── handoff.json               # Structured handoff (only on "执行任务")

文件	创建时间	用途
discussion.md	阶段 1	所有分析内容：会话元数据、逐轮发现、多视角综合、决策、意图覆盖情况、结论和建议。覆盖的部分：## Current Understanding。追加的部分：## Discussion Timeline。
state.json	阶段 0	机器可读数据：当前轮次、维度评分、置信度历史、质量跟踪（压力测试结果、挑战模式、停滞计数器）、探索元数据。每轮更新。
exploration-codebase.json	阶段 2	代码库上下文：project_type、relevant_files[{path, relevance, summary, dimensions[]}]、patterns[{pattern, files, description}]、constraints[]、integration_points[{location, description}]、key_findings[]、_metadata{timestamp, exploration_scope}
research.json	阶段 2	外部研究：findings[{finding, detail, confidence, source_url}]、best_practices[{practice, rationale, source}]、alternatives[{option, pros, cons, verdict}]、pitfalls[{issue, mitigation, source}]、codebase_gaps[{gap, current_approach, recommended_approach}]、sources[{title, url, key_takeaway}]
handoff.json	阶段 4	仅在“执行任务”时创建：source、session_id、session_folder、summary、implementation_scope[{objective, rationale, priority, target_files[], acceptance_criteria[], change_summary}]、code_anchors[]、key_files[]、key_findings[]、decision_context[]、exploration_artifacts{exploration_codebase, research}——键与 workflow-lite-plan 的 artifactMapping 对齐

---

分析流程

Phase 0: Session Setup
   ├─ Parse topic, flags, generate session ID
   ├─ Detect project root (git rev-parse --show-toplevel || pwd)
   ├─ Create session folder (or detect existing → continue)
   ├─ Initialize state.json + discussion.md
   └─ functions.update_plan([phase-1..phase-4, next-step])

Phase 1: Topic Understanding
   ├─ Identify analysis dimensions from topic keywords
   ├─ Scope with user: focus, perspectives (1-4), depth
   ├─ Generate initial questions from dimensions
   └─ Write initial sections to discussion.md

Phase 2: Exploration
   ├─ Load project specs (ccw spec load)
   ├─ Codebase search → exploration-codebase.json
   ├─ External research via web.run → research.json
   ├─ Multi-perspective analysis → write to discussion.md
   ├─ Context budget gate (>30 files → rank + trim)
   ├─ Initial intent coverage check
   └─ Baseline confidence scoring → state.json

Phase 3: Interactive Discussion (max 5 rounds)
   ├─ Present findings + confidence + weakest dimension
   ├─ User direction: Deepen / Research / Adjust / Complete
   ├─ Cumulative context: always include prior findings
   ├─ Record-before-continue: write to discussion.md BEFORE state update
   ├─ Quality mechanisms:
   │   ├─ Pressure pass (mandatory ≥1 before Phase 4)
   │   ├─ Challenge injection (auto, round ≥2)
   │   ├─ Stall detection (2 consecutive no-progress rounds)
   │   └─ Re-score confidence → state.json
   ├─ Pre-synthesis readiness gate (on "Complete")
   ├─ Intent drift check (round ≥2)
   └─ Update discussion.md: append round + overwrite Current Understanding

Phase 4: Synthesis & Terminal Gate
   ├─ Intent Coverage Verification (mandatory gate)
   ├─ Findings → Recommendations Traceability (mandatory gate)
   ├─ Write synthesis + conclusions to discussion.md
   ├─ Recommendation review with user
   └─ Terminal gate: 执行任务 → handoff.json | 产出Issue | 完成

---

阶段 0：会话设置

1. 解析 {{ARGUMENTS}}，获取主题和标志（--depth、--continue、-y）
2. 检测项目根目录：git rev-parse --show-toplevel 2>/dev/null || pwd
3. 生成会话 ID：ANL-{date}-{slug}，会话文件夹：{projectRoot}/.workflow/.analysis/{sessionId}
4. 如果会话文件夹中存在 discussion.md → 自动进入继续模式（加载 state.json，从上一轮继续）
5. 创建会话文件夹：mkdir -p {sessionFolder}
6. 初始化 state.json：

{
  "session_id": "ANL-{date}-{slug}",
  "topic": "...",
  "depth": "standard",
  "dimensions": [],
  "perspectives": [],
  "focus_areas": [],
  "current_round": 0,
  "current_phase": "setup",
  "confidence": {
    "dimensions": {},
    "overall": 0,
    "weakest": null,
    "history": []
  },
  "quality": {
    "pressure_pass_done": false,
    "challenge_modes_used": [],
    "stall_counter": 0,
    "last_findings_count": 0,
    "readiness_gate_passed": false,
    "residual_risks": []
  }
}

7. 初始化进度跟踪：

functions.update_plan([
  { id: "phase-1", title: "Phase 1: Topic Understanding", status: "in_progress" },
  { id: "phase-2", title: "Phase 2: Exploration & Research", status: "pending" },
  { id: "phase-3", title: "Phase 3: Interactive Discussion", status: "pending" },
  { id: "phase-4", title: "Phase 4: Synthesis & Conclusion", status: "pending" },
  { id: "next-step", title: "GATE: Post-Completion Next Step", status: "pending" }
])

---

阶段 1：理解主题

1.1 识别维度

将主题关键词与分析维度匹配。如果匹配到多个维度，则全部纳入。如果没有匹配项，则默认使用“架构”+“实现”。

1.2 初始范围界定（新会话，非自动模式）

调用一次 functions.request_user_input，最多包含 3 个问题（限制：1-4 个问题，每个问题提供 2-4 个选项）：

问题 1 — 关注领域（multiSelect: true）：

• 使用 维度-方向映射 根据匹配的维度动态生成选项，最多 4 个选项

问题 2 — 视角（multiSelect: true）：

• 技术：实现模式、代码结构、可行性
• 架构：系统设计、可扩展性、交互
• 安全：安全模式、漏洞、访问控制
• 性能：瓶颈、优化、资源利用率

最多 4 种视角。默认选择单一视角。

问题 3 — 深度（multiSelect: false）：

• 标准（推荐）：均衡分析，覆盖充分
• 快速概览：快速了解表面情况
• 深入探究：全面的多轮调查

1.3 初始化 discussion.md

写入完整的初始模板（参见 discussion.md 结构）：

• 标题：会话 ID、主题、时间戳（UTC+8）、维度、深度
• 目录（每轮自动更新）
• 当前理解：“将在探索后填写”
• 分析上下文：关注领域、视角、深度
• 初始问题：根据主题和维度生成（分析应解答的关键问题）
• 初始决策：记录选择这些维度/关注领域的原因、未纳入哪些内容及原因
• 讨论时间线：留空，稍后追加各轮内容
• 决策轨迹：留空，在阶段 4 中填写

使用维度、视角、focus_areas、深度更新 state.json。将 phase-1 标记为 completed，将 phase-2 标记为 in_progress。

---

阶段 2：探索

所有探索均在当前流程中完成，不委派给 Agent。

2.1 检测代码库并加载规范

检测项目类型：

• package.json → nodejs | go.mod → golang | Cargo.toml → rust | pyproject.toml → python | pom.xml → java | 存在 src/ → generic | 否则 → none

如果检测到代码库，加载项目元数据：

• functions.exec_command('ccw spec load --category exploration')
• functions.exec_command('ccw spec load --category debug')
• 阅读 .workflow/specs/*.md，了解项目约定

2.2 搜索代码库

使用以下工具搜索：Grep、Glob、Read、mcp__ace-tool__search_context

重点关注：与主题相关的模块/组件、代码模式/结构、集成点、配置/依赖项。

将发现写入 exploration-codebase.json，使用完整架构：

• project_type：检测到的类型
• relevant_files[]：{path, relevance, summary, dimensions[]}
• patterns[]：{pattern, files, description}
• constraints[]：发现的架构约束
• integration_points[]：{location, description}
• key_findings[]：代码搜索得出的主要见解
• _metadata：{timestamp, exploration_scope}

2.3 外部研究

触发条件：维度包含 architecture|comparison|decision|performance|security，或主题匹配 best practice|pattern|vs|compare|approach|standard|library|framework。

对于纯内部代码库问题（例如“模块 X 的工作方式”），跳过此步骤。

最多执行 3 次 web.run 查询：

• {topic} best practices {year}
• {topic} common pitfalls and known issues
• 针对每个匹配维度：{topic} {dimension} patterns and recommendations

将发现写入 research.json，使用完整架构：

• findings[]：{finding, detail, confidence, source_url}
• best_practices[]：{practice, rationale, source}
• alternatives[]：{option, pros, cons, verdict}
• pitfalls[]：{issue, mitigation, source}
• codebase_gaps[]：{gap, current_approach, recommended_approach}
• sources[]：{title, url, key_takeaway}
• _metadata：{queries_executed, timestamp}

交叉比对：将代码库模式与研究所得最佳实践的差异标记为 codebase_gaps。

2.4 多视角分析

单一视角（默认）：结合探索和研究上下文，全面分析所有维度。将发现直接写入 discussion.md Round 1。

多视角（2-4 个视角，依次进行）：依次分析每个视角。针对每个视角，在 discussion.md Round 1 中写入一个摘要小节。然后追加一个综合小节：

• 共识主题：所有视角一致认同的内容
• 不同观点：各视角存在分歧之处
• 独特贡献：特定视角独有的见解

2.5 上下文预算门槛

如果探索在 exploration-codebase.json 中发现了 > 30 个相关文件：

• 按相关性评分排序，每个维度保留前 30 个
• 更新 exploration-codebase.json，写入精简后的列表和 _budget{original_count, summarized_count}
• 在 discussion.md 中注明：“探索发现 N 个相关文件，已精简至 30 个高相关文件”

2.6 将 Round 1 写入 discussion.md

使用 Round Template 追加到 Discussion Timeline：

• 已分析的来源、有证据引用的关键发现（file:line）
• 外部研究发现、最佳实践、代码库缺口
• 多视角综合（如适用）
• 讨论要点和待解决问题
• Decision Log：选择特定搜索策略/视角的原因

2.7 初始意图覆盖检查

从 discussion.md 标题中提取用户的原始意图。对照 Round 1 的发现检查每项意图：

• ✅ 已覆盖
• 🔄 进行中
• ❌ 尚未讨论

在 discussion.md 中追加：“接下来的讨论将重点关注未覆盖 (❌) 和进行中 (🔄) 的意图。”

2.8 基线置信度评分

根据 5 个加权因素对每个维度评分（每项 [0.0, 1.0]）：

因素	权重	衡量内容
findings_depth	0.30	发现的深入程度
evidence_strength	0.25	硬证据与推断的对比
coverage_breadth	0.20	对该维度的覆盖程度
user_validation	0.15	用户确认的发现（初始为 0，在 Phase 3 中增加）
consistency	0.10	发现之间没有矛盾

总体置信度 = 各维度的加权平均值。找出最弱的维度。

更新 state.json 中的 confidence 部分。在 discussion.md 中追加置信度表：

#### Confidence Score (Baseline)
| Dimension | Depth | Evidence | Coverage | Validation | Consistency | **Score** |
|-----------|-------|----------|----------|------------|-------------|-----------|
| {dim}     | {x}   | {x}     | {x}      | 0.00       | {x}         | **{x}**   |

Overall: {N}% | Weakest: {dim} ({N}%)
> < 60%: 建议继续深入 | 60-80%: 可选深入或收敛 | > 80%: 建议收敛到结论

Phase 2 退出条件：已创建 exploration-codebase.json（如有代码库）、已创建 research.json（如主题需要）、已将 Round 1 更新至 discussion.md、已完成初始意图覆盖检查、已计算基线置信度。

将 phase-2 标记为 completed，将 phase-3 标记为 in_progress。

---

Phase 3：交互式讨论

最多 5 轮。每轮遵循以下顺序。

累积上下文规则

Phase 3 中的每项分析操作都必须包含所有既往发现的摘要，以避免重复发现已知信息：

## KNOWN FINDINGS (DO NOT re-discover)
- Established files: {list from exploration-codebase.json}
- Key findings: {from discussion.md rounds}
- Open questions: {remaining}
## NEW TASK: Focus ONLY on unexplored areas below.

3.1 展示发现并收集方向

Round ≥ 2 前言：用 1-2 句话回顾已达成的共识、上一轮的方向以及置信度变化。例如：“到目前为止，我们已确认 [facts]。上一轮 [direction]。置信度从 52% 提升到 67%，security 维度仍需深入。”

从 state.json 读取最新置信度。找出最弱的维度。

通过 functions.request_user_input 展示（单个问题，multiSelect: false，4 个选项）：

• 继续深入：{weakest_dimension}（推荐） — 深入分析置信度最低的维度
• 外部研究 — 使用 web.run 研究特定技术/模式
• 调整方向 — 更改重点或提出具体问题
• 分析完成 — 进入综合阶段（触发就绪门槛）

问题标题显示：Round {N} | Confidence: {N}% | 最弱: {dim} ({N}%)

3.2 处理响应

记录后再继续规则：下方每条路径都必须先将发现和讨论综合内容写入 discussion.md，再继续进行状态更新或下一轮。

记录检查点（所有路径）：记录用户的原始选择、对方向的影响，以及方向发生变化时的完整决策记录。

技术方案触发条件：当描述的实现方法包含具体文件／模式、对比了 2 个或更多备选方案，或用户确认／否决了某种方法时 → 使用技术方案格式记录。

歧义检查：对于状态为“Proposed”的每项技术方案，确认不存在尚未解决的备选方案。如果存在 2 个或更多选项，但尚未选定其中一个 → 标记：

> **⚠️ Ambiguity**: [Solution] has [N] unresolved alternatives: [list]
> - **Needs**: [Decision criteria or exploration to resolve]

在下一轮反馈中向用户说明。

继续深入

通过 functions.request_user_input 提出子问题（multiSelect: false，最多 4 个选项）：

• 最多 3 个由上下文驱动的选项，根据未解决的问题、置信度较低的发现、尚未探索的维度生成
• 1 个启发式选项：“换角度审视”——与最佳实践、不同视角或更简单的替代方案进行比较
• 自动提供“Other”，供用户指定自定义方向

使用 Grep/Glob/Read/mcp__ace-tool__search_context 执行内联搜索。将新发现与此前的上下文合并。记录已确认的假设和探索角度。

外部研究

通过 functions.request_user_input 询问研究主题（最多 4 个选项）：

• 最多 3 个建议，来自未解决的技术问题、未经验证的模式
• 1 个自定义选项：“自定义”（通过 Other）

执行 web.run({search_query: "{topic} best practices {year}"})。将发现合并到 research.json 中（追加而非覆盖）。在 discussion.md 中将其记录为关键发现。与代码库交叉核对；将新的 codebase_gaps 标记出来。

调整方向

询问新的重点。从调整后的视角进行分析。将新见解与此前的分析进行比较。将其记录为决策：触发因素、旧方向→新方向、预期影响。

分析完成

触发综合前就绪门槛。如果通过 → 进入第 4 阶段。如果被阻止 → 由用户选择解决差距或接受风险（将剩余风险记录在 state.json + discussion.md 中）。

记录为何在本轮结束分析。

3.3 记录轮次

使用轮次模板，将以下内容追加到讨论时间线：用户输入、决策日志、关键发现、技术方案、分析结果、已修正的假设、未解决事项、置信度评分、叙述性综合。

按照整合规则，用最新整合后的状态覆盖（而非追加）## Current Understanding。

使用新的 Round N 链接更新 ## Table of Contents。

3.4 质量机制

每轮记录完成后执行。

压力测试（强制，至少在第 4 阶段前执行一次）

当 quality.pressure_pass_done 为 false，且当前轮次存在关键发现时：

选择置信度最高的发现，并按顺序应用压力阶梯：

1. 要求证据：“有哪些具体证据支持这一点？是否存在反例？”
2. 探查假设：“要使这一点成立，隐含了什么假设？它依赖于什么？”
3. 边界／权衡：“如果接受这一点，我们必须放弃什么或明确排除什么？”
4. 检查根本原因：“这是根本原因，还是更深层问题的症状？”

持续审视同一项发现，直到它得到验证或修正——不要为了覆盖更多内容而切换目标。经受住检验的发现将提升为高置信度；未能经受住检验的发现则予以标记。

记录在 discussion.md 中：

#### Pressure Pass (Round N)
> **Target**: [finding]
> - **Confidence claimed**: [level] | **Evidence**: [assessment]
> - **Hidden assumption**: [identified]
> - **Boundary impact**: [tradeoff or scope consequence]
> - **Verdict**: [Confirmed with evidence / Weakened — needs more data / Corrected]

在 state.json 中将 quality.pressure_pass_done = true。

挑战模式注入（自动，轮次 ≥ 2）

每种模式每个会话最多触发一次。在 quality.challenge_modes_used[] 中跟踪。

模式	触发条件	挑战
魔鬼代言人	轮次 2+ 且任一维度的置信度 > 0.7	"如果 [finding] 不成立，分析结论会如何改变？有什么证据可能推翻它？"
范围最小化器	关键发现数量 > 5 且范围正在扩大（新增维度）	"哪些发现可以合并？最小可行结论集是什么？是否在分析不必要的方面？"
根因探查	用户反馈包含因果表述（"因为"、"导致"、"由于"）	"这是根因还是症状？上游还有什么因素在起作用？"

记录到 discussion.md：

#### Challenge: {Mode}
> **Target**: [finding or observation]
> **Counter-scenario / Question**: [challenge content]
> **Result**: [survived / weakened / corrected]

停滞检测

每轮结束后，评估：是否有新发现？是否修正了假设？置信度变化是否 > 5%？

如果连续 2 轮以上均无上述变化（quality.stall_counter >= 2）：

• 自动注入根因探查（如果尚未使用）
• 通过 functions.request_user_input 向用户展示（3 个选项）：
  • 切换维度（推荐）：切换到最薄弱或尚未探索的维度
  • 外部研究：通过外部最佳实践打破僵局
  • 收敛结论：当前发现已足够，继续进行综合整理
• 重置停滞计数器

重新评估置信度

重新计算所有维度的评分。随着用户在多轮中确认发现，user_validation 因子的权重增加。

更新 state.json：confidence.dimensions、confidence.overall、confidence.weakest，并追加到 confidence.history[{round, overall, dimensions}]。

追加到 discussion.md：

#### Confidence Score (Round N)
Overall: {N}% ({+/-N}%) | Weakest: {dim} ({N}%)

3.5 综合整理前就绪门槛

用户选择“分析完成”时触发。若存在以下任一情况，则阻止退出：

1. ❌ 最新覆盖检查中仍存在未覆盖意图
2. 任一维度的置信度低于 40%，且未明确延期
3. quality.pressure_pass_done 为 false
4. 存在尚未解决的技术方案歧义（状态为“已提出”，且有 2 个或更多备选方案）

如果发现缺口 → 通过 functions.request_user_input 展示（2 个选项）：

• 补充后完成（推荐）：继续第三阶段，针对缺口进行分析
• 忽略风险并继续：将遗留风险记录到 state.json quality.residual_risks[] 和 discussion.md，然后进入第四阶段

3.6 意图偏移检查（轮次 ≥ 2）

重新阅读 discussion.md 标题中的原始意图。与第二阶段基线进行比较：

• ✅ 已在第 N 轮处理
• 🔄 正在处理中，当前关注点
• ⚠️ 已隐式纳入 X — 需要明确确认（已纳入 ≠ 已处理）
• ❌ 尚未讨论

如果存在 ⚠️ 或 ❌ → 主动提示：“以下原始意图尚未充分覆盖：[list]。是否需要调整优先级？”

第三阶段退出条件：至少完成 1 次压力测试，每轮均评估置信度，通过就绪门槛（或接受风险），在满足触发条件时触发挑战模式，需要时进行停滞干预，并完整更新 discussion.md。

将第三阶段标记为 completed，将第四阶段标记为 in_progress。

---

第四阶段：综合整理与终止门槛

4.1 意图覆盖验证（强制门槛）

将意图覆盖矩阵写入 discussion.md：

### Intent Coverage Matrix
| # | Original Intent | Status | Where Addressed | Notes |
|---|----------------|--------|-----------------|-------|
| 1 | [text] | ✅ Addressed | Round N, Rec #M | |
| 2 | [text] | 🔀 Transformed | Round N → M | Original: X → Final: Y |
| 3 | [text] | ⚠️ Absorbed | Round N | Covered by Rec #M |
| 4 | [text] | ❌ Missed | — | Reason |

门槛：❌ 项目必须（a）在额外一轮中处理，或（b）经用户明确确认后延期。

4.2 发现到建议的可追溯性（强制门槛）

收集所有轮次中所有可执行的发现。来源：包含可执行影响的关键发现、技术方案（已提出/已验证）、已识别的缺口，以及意味着需要修正的已纠正假设。

为每项指定处置方式：

处置方式	含义
recommendation	转化为编号建议
absorbed	已由另一项建议涵盖（注明是哪一项）
deferred	超出范围并说明原因
informational	纯粹的见解，无需采取行动

门槛：所有发现都必须指定处置方式。不允许为空。

写入 discussion.md：

### Findings Coverage Matrix
| # | Finding (Round) | Disposition | Target |
|---|----------------|-------------|--------|
| 1 | [finding] (R1) | recommendation | Rec #1 |
| 2 | [finding] (R2) | absorbed | → Rec #1 |
| 3 | [finding] (R3) | deferred | Low priority, future work |
| 4 | [finding] (R1) | informational | — |

4.3 将综合结果写入 discussion.md

追加以下部分：

综合与结论：

• 执行摘要
• 关键结论：{point, evidence, confidence: high|medium|low}
• 建议（按优先级从高到低）：每项包含 action（祈使动词 + 目标）、rationale、priority、evidence_refs（文件:行号）、steps[{description, target, verification}]
• 未解答的问题
• 后续建议：{type: issue|task|research, summary}

当前理解（最终版）——覆盖为：

• 已确认的内容：已确认的要点、已验证的发现
• 已澄清的内容：重要的 错误 → 正确 更正
• 关键见解：值得留作未来参考的经验

决策轨迹：

• 影响结果的关键决策
• 附带理由的方向变更时间线
• 做出的权衡及其原因

会话统计：总轮数、关键发现数量、涵盖的维度、生成的产物、决策数量、最终置信度分数、质量信号摘要（压力测试通过、使用的挑战模式、停滞事件）。

使用最终置信度和质量信号更新 state.json。

4.4 建议审查（自动模式下跳过）

通过 functions.request_user_input 批量提问——每次最多 4 个问题，按优先级从高到中到低排序：

每项建议提供 3 个选项：

• 确认（推荐）：按原样接受 → 状态为 "accepted"
• 修改：调整范围/步骤 → 跟进询问详细信息 → 状态为 "modified"
• 删除：不需要 → 状态为 "rejected"

将所有审查决定记录到 discussion.md + state.json。

追加审查摘要：

### Recommendation Review Summary
| # | Action | Priority | Steps | Status | Notes |
|---|--------|----------|-------|--------|-------|
| 1 | [action] | high | 3 | ✅ Accepted | |
| 2 | [action] | medium | 2 | ✏️ Modified | [notes] |
| 3 | [action] | low | 1 | ❌ Rejected | [reason] |

4.5 终结关卡（必须执行）

未完成此步骤，工作流即为未完成。

将 phase-4 标记为 completed，将 next-step 标记为 in_progress。

functions.request_user_input（3 个选项）：

• 执行任务（推荐）：构建实施范围，移交给规划阶段
• 生成 Issue：将建议转换为受跟踪的 Issue
• 完成：显示产物路径，结束

执行任务

步骤 A——构建范围：筛选状态为 "accepted" 或 "modified" 的建议。按优先级排序。每项包含：{objective, rationale, priority, target_files[], acceptance_criteria[], change_summary}。

步骤 B——用户确认范围（自动模式下跳过）：展示范围摘要，然后调用 functions.request_user_input（3 个选项）：

• 确认执行（推荐）：继续移交
• 调整范围：缩小或扩大范围 → 重新确认
• 补充标准：添加/完善验收标准 → 重新确认

步骤 C——写入 handoff.json（架构与 workflow-lite-plan 产物桥接保持一致）：

{
  "source": "analyze-with-file",
  "session_id": "...",
  "session_folder": "...",
  "summary": "...",
  "implementation_scope": [
    { "objective": "...", "rationale": "...", "priority": "high|medium|low",
      "target_files": [], "acceptance_criteria": [], "change_summary": "..." }
  ],
  "code_anchors": [],
  "key_files": [],
  "key_findings": [],
  "decision_context": [],
  "exploration_artifacts": {
    "exploration_codebase": "{sessionFolder}/exploration-codebase.json",
    "research": "{sessionFolder}/research.json"
  }
}

Codex 版本没有单独的 explorations.json/perspectives.json（所有内容都在 discussion.md 中）。只有 exploration_codebase 和 research 是基于文件的产物。

步骤 D——向 discussion.md 追加计划清单：

## Plan Checklist
> **This is a plan only — no code was modified.**
- **Recommendations**: {count}
- **Generated**: {timestamp}

### 1. {objective}
- **Priority**: {level}
- **Rationale**: {reason}
- **Target files**: {list or TBD}
- **Acceptance criteria**: {list}
- [ ] Ready for execution

生成 Issue

对每项已接受的建议，使用 ccw issue create 并设置：

• title：建议中的行动
• context：行动 + 理由 + 证据引用
• priority：high→2，medium/low→3
• source："discovery"
• labels：分析维度

显示已创建的 Issue ID，并提示下一步。

完成

显示产物路径，结束。

将 next-step 标记为 completed。整个过程中不修改源代码。

---

记录协议

触发规则

发生以下情况时，立即记录到 discussion.md：

触发条件	目标章节
方向选择 / 范围调整	#### 决策日志
发现关键结果	#### 关键发现
更正假设	#### 已更正的假设
收到用户反馈	#### 用户输入
存在分歧或需要权衡	#### 决策日志
提出/验证/否决技术方案	#### 技术方案
执行压力测试	#### 压力测试
触发挑战模式	#### 挑战

记录格式

决策：

> **Decision**: [description]
> - **Context**: [trigger]
> - **Options considered**: [alternatives]
> - **Chosen**: [approach] — **Reason**: [rationale]
> - **Rejected**: [why others discarded]
> - **Impact**: [effect on direction/conclusions]

发现：

> **Finding**: [content]
> - **Confidence**: [High/Medium/Low] — **Why**: [evidence basis]
> - **Hypothesis Impact**: [Confirms/Refutes/Modifies] hypothesis "[name]"
> - **Scope**: [affected areas]

技术方案（记录时机：采用了涉及具体文件／模式的实现方案、比较了 2 种以上方案、用户确认／修改／否定了方案，或形成了具体的代码变更策略）：

> **Solution**: [approach/pattern/implementation]
> - **Status**: [Proposed / Validated / Rejected]
> - **Problem**: [what it solves]
> - **Rationale**: [why this approach]
> - **Alternatives**: [other options, why not chosen]
> - **Evidence**: [file:line refs]
> - **Next Action**: [follow-up or none]

叙述性综合（每轮结束后追加）：

### Round N: Narrative Synthesis
**起点**: 基于上一轮的 [conclusions/questions]，本轮从 [starting point] 切入。
**关键进展**: [findings] [confirmed/refuted/modified] 了关于 [hypothesis] 的理解。
**决策影响**: 用户选择 [feedback type]，分析方向 [adjusted/deepened/maintained]。
**当前理解**: 核心认知更新为 [updated understanding]。
**遗留问题**: [remaining questions]

原则

• 及时性：决策发生时立即记录，而不是等到阶段结束
• 完整性：记录背景、选项、选定方案、理由、被否决方案和影响
• 可追溯性：后续阶段可以追溯任何决策
• 深度：记录推理和假设的影响，而不只是结果

---

discussion.md 结构

# Analysis Discussion

**Session**: {id} | **Topic**: {topic} | **Started**: {timestamp}
**Dimensions**: {list} | **Depth**: {level}

## Table of Contents


## Current Understanding

### What We Established
### What Was Clarified
### Key Insights

## Analysis Context
- Focus areas: {list}
- Perspectives: {list}
- Depth: {level}

## Initial Questions
- {generated from topic + dimensions}

## Initial Decisions
> Record WHY these dimensions/focus areas were selected, what was excluded and why.

---
## Discussion Timeline

### Round 1 - Exploration ({timestamp})
#### Key Findings
#### Decision Log
#### Technical Solutions
#### Analysis Results
#### External Research
#### Multi-Perspective Synthesis
#### Intent Coverage Check
#### Confidence Score (Baseline)
#### Narrative Synthesis

### Round N - [Deepen|Research|Adjust] ({timestamp})
#### User Input
#### Decision Log
#### Key Findings
#### Pressure Pass
#### Challenge
#### Technical Solutions
#### Analysis Results
#### Corrected Assumptions
#### Open Items
#### Confidence Score (Round N)
#### Intent Coverage Check
#### Narrative Synthesis

---
## Synthesis & Conclusions
### Intent Coverage Matrix
### Findings Coverage Matrix
### Executive Summary
### Key Conclusions
### Recommendations
### Recommendation Review Summary
### Open Questions

## Decision Trail

## Plan Checklist (if 执行任务)

## Session Statistics

整合规则

覆盖 ## Current Understanding 时：

规则	说明
提炼已确认的见解	将已验证的发现移至“已确立事项”
追踪更正	保留重要的 错误 → 正确 转变
聚焦当前状态	记录当前已知信息，而不是探索过程
避免重复时间线	不要将讨论细节复制到整合后的章节中
保留关键经验	保留对未来参考有价值的见解

错误示例：“第 1 轮我们讨论了 X，然后第 2 轮用户说了 Y……” 正确示例：使用结构化小节（已确立／已澄清／关键见解），只记录当前状态的事实。

---

参考

分析维度

维度	关键词
架构	架构, architecture, design, structure, 设计, pattern
实现	实现, implement, code, coding, 代码, logic
性能	性能, performance, optimize, bottleneck, 优化, speed
安全	安全, security, auth, permission, 权限, vulnerability
概念	概念, concept, theory, principle, 原理, understand
比较	比较, compare, vs, difference, 区别, versus
决策	决策, decision, choice, tradeoff, 选择, trade-off

分析视角

视角	重点	最适合
技术	实现模式、代码结构、可行性	实现方式和技术细节
架构	系统设计、可扩展性、组件交互	结构和组织
安全	安全模式、漏洞、访问控制	安全风险
性能	瓶颈、优化、资源利用率	性能问题

深度级别

深度	范围
快速	浅层分析，最少探索
标准	均衡分析，覆盖充分（默认）
深入	全面开展多轮调查

维度与方向映射

根据匹配的维度动态生成关注方向选项：

维度	可能的方向
架构	系统设计、组件交互、技术选型、集成点、设计模式、可扩展性策略
实现	代码结构、实现细节、代码模式、错误处理、测试方法、算法分析
性能	性能瓶颈、优化机会、资源利用率、缓存策略、并发问题
安全	安全漏洞、身份验证／授权、访问控制、数据保护、输入验证
概念	概念基础、核心机制、基本模式、理论与原则、权衡与推理
比较	方案比较、优缺点分析、技术评估、方法差异
决策	决策标准、权衡分析、风险评估、影响分析、实施影响

每个匹配的维度展示 2–3 个优先方向，支持多选和自定义方向。

---

错误处理

情况	操作	恢复方式
未检测到代码库	仅分析主题	跳过代码库搜索
代码库搜索失败	使用现有上下文继续	在 discussion.md 中注明限制
没有相关发现	扩大关键词范围	请用户澄清
用户超时	保存状态	使用 --continue 恢复
达到最大轮数（5）	强制综合分析	突出显示尚未解决的问题
会话文件夹冲突	添加时间戳后缀	创建唯一文件夹
未生成建议	无计划生成	告知用户并建议替代方案
网络研究失败	仅基于代码库进行分析	注明限制，并标记为 codebase_gaps
研究结论与代码库冲突	标记为 codebase_gaps	呈现差异，供用户审查
分析停滞（2 轮以上）	自动加入质疑	用户：切换维度 / 继续研究 / 收敛结论
就绪检查门阻止退出	显示差距摘要	用户弥补差距或接受风险
超出上下文预算	排序并精简至前 30 项	在 discussion.md 中注明

---

适用场景

在以下情况下使用此技能：探索复杂主题、多轮完善认知、从多个角度进行决策、在实现前建立共同认知，以及需要留存包含外部研究的分析过程。

考虑其他方案：

• Bug 诊断 → debug-with-file
• 创意生成 → brainstorm-with-file
• 准备开始实现 → lite-plan

---

现在针对以下主题执行 analyze-with-file 工作流：$TOPIC