标签建议：area/dx, documentation, priority/P0, dependency/foundation
背景
当前仓库已有不少高质量功能 issue，例如 #6（输入历史持久化）和 #8（TUI 会话管理）。这类 issue 的共同点是：
- 背景清楚：说明当前行为、真实痛点和为什么值得做。
- 目标明确：一句话定义要交付的能力。
- 用户故事具体：能看出谁会用、怎么用、为什么有价值。
- 详细需求可实现：包含命令、文件结构、数据格式、流程、边界和兼容性。
- 验收标准可测试：每个 checkbox 都能被实现者和 reviewer 验证。
- 测试方案提前写明：单元、集成、冒烟或手动验证范围清楚。
- 风险和非本期范围明确：避免 issue 膨胀成无边界需求。
为了让后续功能 issue 都能直接进入实现和评审，需要把 #6/#8 的写法沉淀成仓库标准。之后新增功能类 issue 默认按这个标准提交；不满足标准的 issue 应先补全信息，再进入开发。
目标
建立 q-code 功能 issue 标准模板，统一功能需求的描述结构、验收口径、测试要求、依赖风险和工作量评估，让后续 issue 更容易拆分、实现、评审和关闭。
用户故事
- 作为需求提出者，我能按一个固定模板描述功能，减少来回追问。
- 作为实现者，我能从 issue 直接看出模块边界、命令形态、数据结构、验收标准和测试命令。
- 作为 reviewer，我能按 checklist 判断 PR 是否真的完成，而不是只看“代码写了”。
- 作为维护者，我能快速判断 issue 是否过大、是否依赖其他 issue、是否需要拆分。
详细需求
1. 标题标准
功能 issue 标题使用：
ext [领域] 功能名称：一句话说明交付结果
示例：
ext [TUI] 输入历史持久化：跨进程的上下方向键 + Ctrl+R [TUI] 会话管理：在 TUI 内列出/切换/删除/导出/重命名会话 [Eval] Agent 质量闭环：优化建议自动化、Trace 回流与更细归因
要求：
[领域] 使用仓库已有 area 语义，例如 TUI、CLI、Eval、Session、Tools、Security、Observability。- 标题不写实现细节堆砌，不写“优化一下”“完善功能”这类模糊表述。
- 冒号后描述用户可感知的结果。
2. 标签标准
正文第一行必须给出标签建议：
` ext
标签建议：area/..., priority/P..., type/feature
`
推荐标签：
| 类型 |
示例 |
说明 |
| area |
area/tui / area/evals / area/session |
所属模块 |
| priority |
priority/P0 / priority/P1 / priority/P2 |
优先级 |
| type |
type/feature / bug / documentation |
issue 类型 |
| dependency |
dependency/foundation / dependency/blocked |
是否基础能力或被阻塞 |
| depends-on |
depends-on/provider 等 |
显式依赖其他 issue |
3. 必填章节
功能 issue 默认必须包含以下章节，顺序建议固定：
` ext
背景
目标
用户故事
详细需求
验收标准
测试方案
不在本期范围
依赖 / 风险
工作量评估
`
允许补充章节：
` ext
输出样例
数据结构
CLI 命令
文件布局
兼容性
隐私 / 安全
关联
`
4. 背景写法
背景要回答：
- 当前系统是什么状态。
- 用户遇到什么真实问题。
- 为什么现有能力不够。
- 这个功能如果不做，会造成什么成本。
推荐写法：
` ext
当前能力：
痛点：
需要补齐：
不要只写“需要优化”“体验不好”，必须给出具体症状或场景。
5. 目标写法
目标必须是一段清晰的交付定义：
ext 实现 <功能>：支持 <核心能力>，并满足 <关键约束>。
示例：
ext 实现 q-code doctor：一次性运行环境/配置/连接/权限检查，输出彩色报告和机器可读 JSON，覆盖大多数已知启动失败类型。
6. 用户故事写法
至少 3 条，使用“作为...我希望...以便...”的真实角色视角。
示例：
` ext
- 作为新用户，我第一次安装后运行
q-code doctor，立刻知道 API Key 和模型是否可访问。
- 作为提 bug 的用户，我能贴
q-code doctor --json 输出，开发者快速定位问题。
`
7. 详细需求写法
详细需求必须可实现、可拆分、可评审。建议按子功能编号：
` ext
1. CLI 入口
2. 文件格式与位置
3. 写入规则
4. 加载与合并
5. 兼容性
`
每个子需求尽量包含：
- 命令形态或 API 形态。
- 文件路径或模块位置。
- 数据格式或接口结构。
- 默认值和配置项。
- 错误处理与边界行为。
- 是否需要同步 README / AGENTS / .env.example。
8. 输出样例标准
凡是新增 CLI、报告、配置、JSON、Markdown 或 TUI 表格，都必须给样例。
CLI 示例：
ext q-code eval run evals/smoke --report json,md,junit
JSON 示例：
json { "status": "pass", "checks": [] }
TUI/文本示例：
ext 总结: 18 通过 · 2 警告 · 0 失败
9. 验收标准写法
验收标准必须是 checkbox，并且每条都能验证。
好的写法：
` ext
不好的写法：
` ext
验收标准至少覆盖：
- 正常路径。
- 失败/异常路径。
- 配置或兼容性路径。
- 文档更新。
- 测试覆盖。
10. 测试方案写法
测试方案必须说明预计新增或修改哪些测试：
` ext
tests/unit/<feature>.test.ts：覆盖纯逻辑和边界。tests/integration/<feature>.test.ts：覆盖真实流程。- 手动验证：
pnpm ...。
`
如果功能涉及 Agent Loop、TUI、MCP、Langfuse、文件系统、并发或网络，必须写明如何避免 flaky。
11. 不在本期范围
必须明确排除项，避免一个 issue 无限膨胀。
示例：
` ext
不在本期范围
- Web Dashboard UI。
- 自动修改源码并提交 PR。
- 云端同步。
`
12. 依赖 / 风险
必须写：
- 依赖哪些 issue 或模块。
- 会不会影响现有行为。
- 安全、隐私、成本、并发、跨平台风险。
- 可能需要的迁移或兼容策略。
13. 工作量评估
使用粗粒度人日估算即可：
` ext
- 框架/API：1 人日
- 核心实现：2 人日
- 测试与文档：1 人日
- 合计：~4 人日
`
超过 8-10 人日的 issue，默认考虑拆分子 issue。
标准模板
后续功能 issue 可以直接复制下面模板：
`markdown
标签建议：area/..., priority/P..., type/feature
背景
当前能力：
痛点：
目标
实现 ...
用户故事
- 作为 ...，我希望 ...，以便 ...
- 作为 ...，我希望 ...，以便 ...
- 作为 ...，我希望 ...，以便 ...
详细需求
1. ...
2. ...
输出样例
ext ...
验收标准
测试方案
tests/unit/...：...tests/integration/...：...- 手动验证：...
不在本期范围
依赖 / 风险
工作量评估
- 实现：... 人日
- 测试 + 文档：... 人日
- 合计：~... 人日
`
验收标准
测试方案
这是流程/规范 issue，不需要代码测试。验证方式：
- 新建功能 issue 时按模板检查章节是否齐全。
- review issue 时按验收标准判断是否能直接进入实现。
不在本期范围
- Bug report 模板：bug 可另建更短模板，重点放复现步骤、预期/实际行为和日志。
- Security report 模板：安全问题应走私密渠道或单独规范。
- PR 模板：PR 描述可后续单独规范。
依赖 / 风险
- 规范过重可能降低轻量想法提交意愿；因此仅对功能类 issue 强制，问题讨论和 bug 可使用精简模板。
- 旧 issue 不强制全部迁移，但 P0/P1 且准备进入实现的 issue 应按本标准补齐。
- 标准需要随仓库实践演进，不应一次写死。
工作量评估
- 创建标准 issue：0.25 人日
- 后续沉淀到 README/AGENTS 或 issue template：0.5 人日
- 合计：~0.75 人日
背景
当前仓库已有不少高质量功能 issue，例如 #6（输入历史持久化）和 #8（TUI 会话管理）。这类 issue 的共同点是：
为了让后续功能 issue 都能直接进入实现和评审，需要把 #6/#8 的写法沉淀成仓库标准。之后新增功能类 issue 默认按这个标准提交；不满足标准的 issue 应先补全信息，再进入开发。
目标
建立 q-code 功能 issue 标准模板，统一功能需求的描述结构、验收口径、测试要求、依赖风险和工作量评估，让后续 issue 更容易拆分、实现、评审和关闭。
用户故事
详细需求
1. 标题标准
功能 issue 标题使用：
ext [领域] 功能名称：一句话说明交付结果示例：
ext [TUI] 输入历史持久化：跨进程的上下方向键 + Ctrl+R [TUI] 会话管理：在 TUI 内列出/切换/删除/导出/重命名会话 [Eval] Agent 质量闭环：优化建议自动化、Trace 回流与更细归因要求：
[领域]使用仓库已有 area 语义，例如 TUI、CLI、Eval、Session、Tools、Security、Observability。2. 标签标准
正文第一行必须给出标签建议：
` ext
推荐标签：
area/tui/area/evals/area/sessionpriority/P0/priority/P1/priority/P2type/feature/bug/documentationdependency/foundation/dependency/blockeddepends-on/provider等3. 必填章节
功能 issue 默认必须包含以下章节，顺序建议固定：
` ext
背景
目标
用户故事
详细需求
验收标准
测试方案
不在本期范围
依赖 / 风险
工作量评估
`
允许补充章节：
` ext
输出样例
数据结构
CLI 命令
文件布局
兼容性
隐私 / 安全
关联
`
4. 背景写法
背景要回答：
推荐写法：
` ext
当前能力：
痛点：
需要补齐：
`
不要只写“需要优化”“体验不好”，必须给出具体症状或场景。
5. 目标写法
目标必须是一段清晰的交付定义：
ext 实现 <功能>：支持 <核心能力>，并满足 <关键约束>。示例：
ext 实现q-code doctor：一次性运行环境/配置/连接/权限检查，输出彩色报告和机器可读 JSON，覆盖大多数已知启动失败类型。6. 用户故事写法
至少 3 条，使用“作为...我希望...以便...”的真实角色视角。
示例：
` ext
q-code doctor，立刻知道 API Key 和模型是否可访问。q-code doctor --json输出，开发者快速定位问题。`
7. 详细需求写法
详细需求必须可实现、可拆分、可评审。建议按子功能编号：
` ext
1. CLI 入口
2. 文件格式与位置
3. 写入规则
4. 加载与合并
5. 兼容性
`
每个子需求尽量包含：
8. 输出样例标准
凡是新增 CLI、报告、配置、JSON、Markdown 或 TUI 表格，都必须给样例。
CLI 示例：
ext q-code eval run evals/smoke --report json,md,junitJSON 示例：
json { "status": "pass", "checks": [] }TUI/文本示例：
ext 总结: 18 通过 · 2 警告 · 0 失败9. 验收标准写法
验收标准必须是 checkbox，并且每条都能验证。
好的写法：
` ext
q-code doctor --json输出合法 JSON，能被jq解析`
不好的写法：
` ext
`
验收标准至少覆盖：
10. 测试方案写法
测试方案必须说明预计新增或修改哪些测试：
` ext
tests/unit/<feature>.test.ts：覆盖纯逻辑和边界。tests/integration/<feature>.test.ts：覆盖真实流程。pnpm ...。`
如果功能涉及 Agent Loop、TUI、MCP、Langfuse、文件系统、并发或网络，必须写明如何避免 flaky。
11. 不在本期范围
必须明确排除项，避免一个 issue 无限膨胀。
示例：
` ext
不在本期范围
`
12. 依赖 / 风险
必须写：
13. 工作量评估
使用粗粒度人日估算即可：
` ext
`
超过 8-10 人日的 issue，默认考虑拆分子 issue。
标准模板
后续功能 issue 可以直接复制下面模板：
`markdown
背景
当前能力：
痛点：
目标
实现 ...
用户故事
详细需求
1. ...
2. ...
输出样例
ext ...验收标准
测试方案
tests/unit/...：...tests/integration/...：...不在本期范围
依赖 / 风险
工作量评估
`
验收标准
测试方案
这是流程/规范 issue，不需要代码测试。验证方式：
不在本期范围
依赖 / 风险
工作量评估