@betterdanlins/ai-memory 0.1.0 → 0.4.0

package/templates/common/.ai/skills/delivery-readiness.md

@@ -0,0 +1,34 @@
+# 交付就绪检查
+
+在功能准备合并、发布或部署时使用。它是基于证据的轻量检查门，不重新做需求澄清或技术设计。
+
+## 深度路由
+
+- S：验证外部契约、相关测试和无意副作用；本地功能不强制生成独立报告。
+- M：检查适用的数据、性能、可观测性、部署和回滚影响，并把证据写回设计文档。
+- L：完整检查质量属性、迁移/回滚、生产验证和运行保障；阻塞项清零前不得标记就绪。
+
+## 流程
+
+1. 读取 final 需求、适用的技术设计、架构基线和代码差异；不复制这些内容。
+2. 逐条验证外部行为契约与验收标准，记录命令、测试或其他证据。
+3. 只检查适用项；不适用必须写原因，不能静默跳过。
+4. 将结果写入 `docs/design/...` 的“交付验证”章节；S 级无设计文档时记入 session-log。
+5. 输出明确结论：`ready`、`conditional` 或 `not-ready`，并列出阻塞项。
+
+启用模型路由时，机械性测试可交给 economy 执行者，但测试策略、安全/迁移/并发场景和最终审查仍由 premium 执行者负责。测试命令直接运行，不调用模型。reviewer 第一轮保持只读，修复后重新审查。
+
+## 检查面
+
+| 检查面 | 必须回答的问题 |
+|---|---|
+| 契约与测试 | 外部契约、技术接口和失败路径是否有验证证据？ |
+| 数据 | Schema/数据迁移顺序、兼容、校验和回滚是否可执行？ |
+| 部署 | 配置、密钥、制品、发布顺序、健康检查和回滚是否明确？ |
+| 性能与容量 | 受影响预算是否验证，瓶颈与扩容触发条件是否仍成立？ |
+| 可观测性 | 日志、关联 ID、指标、错误上报和告警能否发现并定位失败？ |
+| 可靠性 | 超时、重试、幂等、降级、备份和恢复是否符合风险等级？ |
+| 安全 | 权限、敏感数据、输入边界和依赖风险是否已检查？ |
+| 运行交接 | 谁能判断发布成功、何时停止或回滚、故障如何处置？ |
+
+不要仅凭“代码已完成”判定 ready，也不要为 S 级本地改动强制搭建生产级设施。

package/templates/common/.ai/skills/feature-design.md

@@ -0,0 +1,35 @@
+# 功能技术设计（how）
+
+输入：已定稿需求、相关架构基线和功能记忆。输出：可直接实施的技术设计，不重新讨论已确认的 what/why。
+
+## 适用性
+
+- S 级需求默认不生成完整设计；只在实现中遵循外部契约并测试。
+- M 级生成精简设计，聚焦实际变化。
+- L 级先更新 `docs/architecture/` 基线，再完成设计和聚焦 critic。
+
+## 流程
+
+1. 读取 `final/<需求名>.md` 的实现交接，以及相关 `docs/architecture/`、源码和 feature 记忆。
+2. 若需求存在矛盾或阻塞开放问题，退回 requirements-flow；不要用实现假设偷偷补需求。
+3. 在 `docs/design/vX.Y.Z/<需求名>.md` 按模板形成设计，只填写适用章节，不涉及也要简述原因。
+4. 为真实边界定义技术接口契约；不要为所有私有函数写文档。
+5. 记录数据模型和质量属性相对项目基线的增量，不复制整份基线。
+6. 检查设计是否可实施、可测试、可迁移、可回滚、可观测。
+7. M 级做一次精简自检；L 级按 critic 方法做独立或聚焦审查。
+8. 更新 `project-state.md` 为 `designed`，实现计划只引用本设计，不重新生成同义 spec。
+
+启用模型路由时，`feature-design` 与需要的 `write-plan` 分别创建 handoff；实现阶段必须重新 prepare，引用最终需求、设计和计划的当前哈希。不要把 brainstorming 对话作为实现输入。
+
+## Superpowers 路由
+
+- S：跳过 brainstorming 和 writing-plans。
+- M：仅当存在无法由基线和约束解决的高影响 how 选择时，使用针对性 brainstorming；设计已可实施时跳过完整 writing-plans。
+- L：可使用 brainstorming 比较重大方案，并用 writing-plans 拆实施阶段；必须把结论回写到本设计，Superpowers 临时产物不是唯一事实源。
+
+## 完成门槛
+
+- 模块职责、依赖和关键流程明确。
+- 跨边界接口、错误、状态、一致性和兼容策略明确。
+- 数据、性能、可观测性、容量/功能扩展、可靠性、安全、部署影响均已判断。
+- 验证、迁移和回滚可执行；假设有验证方式。

package/templates/common/.ai/skills/memory-update.md

@@ -1,24 +1,29 @@
-# 记忆更新协议(节点式)
+# 记忆更新协议（工程节点）
 
 ## 触发时机
 
-1. **完成一个任务节点 / 做出关键决策 → 立即写**,不攒到会话结束(主路径)
-2. 用户说「更新记忆」或 /update-memory
-3. 会话收尾、上下文即将压缩
-4. 需求状态变化(requirements-flow 第 5 步联动)
+只在信息对后续会话仍有价值时写入：
+
+1. 完成一个可独立验收的功能、阶段或发布节点。
+2. 做出会约束后续实现的关键决策，或推翻已有决策。
+3. 需求/设计/实现/交付状态变化。
+4. 发现需要跨会话保留的风险、故障原因或踩坑。
+5. 会话中断、上下文压缩或跨工具切换前。
+
+不要因为写了一个测试、修改一个私有函数、执行一次命令或完成细碎 plan item 单独更新记忆。
 
 ## 写入路由
 
 | 内容 | 去处 |
 |---|---|
-| 进展流水(做到哪/下一步/踩坑) | `session-log.md` 带时间戳追加 |
-| 需求/里程碑状态变化 | `project-state.md` 对应表格行 |
-| 功能设计决策、契约变更 | `features/<名>.md` |
-| 新增记忆文件 | `MEMORY.md` 加索引行 |
+| 工程节点、当前进度、下一步、阻塞 | `session-log.md` 追加 |
+| 需求、设计、里程碑或交付状态 | `project-state.md` 对应行 |
+| 稳定功能决策与契约变化摘要 | `features/<名>.md` |
+| 新增记忆文件 | `MEMORY.md` 加索引 |
 
-## 硬性约束
+## 约束
 
-- 写前先读目标文件
-- 只增量追加,不重构既有格式与历史条目
-- session-log 超约 200 行:把旧条目压缩进 project-state.md 的归档章节
-- 跨工具切换前确认 session-log 已落盘;记忆变更随代码一起 commit
+- 写前读取目标文件，只记录增量和新事实，不复制需求/设计/测试输出。
+- 将同一工程节点内的相关小步骤合并为一条，避免流水噪声。
+- session-log 超约 200 行时，把旧条目压缩进 project-state 归档章节。
+- 跨工具切换前确认关键状态已落盘；记忆变更随对应代码或文档一起 commit。

package/templates/common/.ai/skills/model-routing.md

@@ -0,0 +1,39 @@
+# 分阶段模型路由与交接
+
+模型路由只选择现有阶段的执行者，不得增加或跳过 S/M/L 风险流程。读取 `.ai/config/model-routing.json`：`inherit` 保持当前模型；`balanced` 使用高级规划、中等实现、便宜测试和高级审查；`quality` 提高实现与诊断等级。
+
+执行 CLI 时优先使用当前环境的 `ai-memory`；若命令不可用，使用 `npx --yes @betterdanlins/ai-memory@{{frameworkVersion}}`。必须固定与项目框架一致的版本，不使用未固定的 latest。
+
+## 执行协议
+
+1. 先由 requirements-flow / feature-design 判断是否需要该阶段，再解析模型等级。
+2. 跨模型执行前，用 `ai-memory workflow prepare` 从正式需求、设计和计划生成 `.ai/runs/<feature>/handoff.json`。
+3. 执行者先运行 `ai-memory workflow verify`，再读取 handoff 中的全部输入；不得用对话摘要替代正式文档。
+4. 输入缺失、哈希变化、路由变化或存在未决问题时停止，不得猜测。
+5. 实现结束后在同一 run 目录写 `<stage>-result.json`，记录变更文件、验收覆盖、测试、设计偏差和未决风险。
+6. reviewer 第一轮只读；修复交给 implementer，修复后重新审查。
+
+## 能力边界与升级
+
+- `premium`：需求定稿、重大方案、计划、对抗性测试和最终审查。
+- `standard`：按已批准计划实现、普通失败诊断。
+- `economy`：根据明确测试矩阵补机械性测试；不得修改生产代码或重新解释契约。
+- `none`：直接运行确定性命令，不调用模型。
+- economy 无法理解契约或发现生产缺陷 → standard；standard 发现设计缺口或连续两次失败 → premium。
+- 安全、权限、资金、隐私、数据迁移和并发问题直接使用 premium。
+
+模型不可用时可降级为 `inherit`，但必须报告一次；不得静默把高风险阶段降为 economy。
+
+## 交接回执最小字段
+
+```json
+{
+  "stage": "implementation",
+  "status": "completed",
+  "changedFiles": [],
+  "acceptanceCoverage": {},
+  "tests": [],
+  "designDeviations": [],
+  "unresolvedRisks": []
+}
+```

package/templates/common/.ai/skills/project-inception.md

@@ -0,0 +1,33 @@
+# 项目工程基线（0→1）
+
+适用：新项目、首次补建架构基线，或会改变系统边界/数据所有权/部署拓扑的重大重构。普通功能迭代不要重复执行。
+
+## 原则
+
+- 只规定语言无关的工程问题；语言、框架、数据库和云平台是项目答案，不是流程前提。
+- 先记录事实，再记录假设；每个关键假设必须有验证方式或触发复审的条件。
+- 采用满足近期目标的最小架构，禁止用“未来可能扩展”代替具体负载或变化场景。
+- 已有项目以现状盘点补建基线，不为套模板而重做架构。
+- 默认不启动 Superpowers 全套流程；仅在存在多个高影响方案且无法用现有约束决策时，选择性使用 brainstorming。
+
+## 工作流
+
+1. 读取项目目标、现有代码/文档和 `.ai/memory/project-state.md`。
+2. 判断是 0→1、新增基线还是重大重构；不适用则停止并转入需求或功能设计流程。
+3. 只询问会改变架构方向的阻塞信息；非阻塞信息采用保守假设并明确标记。
+4. 按 `docs/architecture/` 的四份模板建立或增量更新工程基线：
+   - `system-context.md`：边界、参与者、模块和关键流程。
+   - `data-model.md`：实体、关系、所有权、生命周期、一致性和迁移。
+   - `quality-attributes.md`：性能、可观测性、扩展性、可靠性、安全、维护性和成本。
+   - `deployment.md`：环境、拓扑、配置、发布、迁移、回滚和运行保障。
+5. 检查四份文档之间是否矛盾；高风险或生产级项目按 `.ai/skills/critic.md` 做一次聚焦审查。
+6. 将确定的技术栈、部署基线和关键风险更新到 `project-state.md`，并在 session-log 记录节点。
+
+## 完成门槛
+
+- 系统内外边界、数据所有权和部署单元明确。
+- 关键质量属性使用“场景 / 条件 / 响应 / 指标 / 验证”表达，而不是形容词。
+- 监控覆盖已知故障；可观测性足以关联请求或任务并定位未知故障。
+- 容量扩展绑定负载场景；功能扩展绑定变化场景。
+- 发布、数据迁移和回滚至少有可执行方向。
+- 所有未知项明确标为假设、风险或开放问题，不伪装成已确认决策。

package/templates/common/.ai/skills/requirements-flow.md

@@ -1,23 +1,40 @@
-# 需求定稿流程(draft → final)
+# 需求定稿流程（draft → final）
 
-触发:用户要求新建/定稿需求,或 /new-requirement、/finalize-requirement。
+本流程只确定 what/why、范围、外部行为和验收标准，不决定模块、存储、框架等 how。技术设计交给 `feature-design`。
 
-## 新建(new)
+## 新建
 
-1. 确认目标版本目录 `docs/requirements/vX.Y.Z/`(不存在则创建 draft/ 与 final/)
-2. 在 `draft/<需求名>.md` 生成骨架:背景 / 想要什么 / 不确定的点
-3. 在 `.ai/memory/project-state.md` 需求进度表登记一行(状态 draft)
+1. 确认版本目录 `docs/requirements/vX.Y.Z/`，不存在则创建 `draft/` 与 `final/`。
+2. 在 `draft/<需求名>.md` 记录：背景 / 想要什么 / 不确定的点。
+3. 在 `project-state.md` 需求进度表登记状态 `draft`。
 
-## 定稿(finalize)
+## 定稿
 
-1. 读 `draft/<需求名>.md`
-2. 逐个澄清模糊点:一次只问一个问题,优先选择题
-3. 按固定结构成稿:**目标 / 范围(必须含「不做什么」)/ 接口契约(格式见 architecture.md)/ 验收标准 / 开放问题**
-4. 强制 critic 门:按 `critic.md` 检查,逐条回应完毕才可写入 `final/<需求名>.md`
-5. 联动记忆:project-state 状态改 finalized;`features/<需求名>.md` 建档登记契约要点;MEMORY.md 加索引行
-6. 需求文档与记忆变更一起 commit
+1. 读取 draft、相关功能记忆和已有外部契约。
+2. 只澄清会改变目标、范围、用户可见行为或验收结果的问题；实现选择留给技术设计。
+3. 按固定结构形成候选稿：
+   - **目标**
+   - **范围**：包含与不做什么
+   - **外部行为契约**：参与者、输入、输出、失败表达、副作用、兼容性
+   - **验收标准**：可观察、可验证
+   - **开放问题**：不得隐藏阻塞项
+   - **实现交接**：已确认决策、how 阶段待决定项、禁止重新讨论项、初步风险等级
+4. 先给出初步风险等级，再按 `.ai/skills/critic.md` 审查需求完整性：S 级做精简同上下文自检，M/L 级使用独立 critic（工具支持时）；逐条处理后才写 `final/<需求名>.md`。
+5. 按下方路由选择下一步，不在本流程中启动重复 brainstorming。
+6. 更新 `project-state.md` 为 `finalized`；在 `features/<需求名>.md` 记录外部契约与关键决策，并更新 MEMORY 索引。
 
-## 与 superpowers 的衔接
+若 `.ai/config/model-routing.json` 的 profile 不是 `inherit`，定稿前按 `.ai/skills/model-routing.md` 为 `requirement-finalize` 准备并校验 handoff，再使用对应等级执行者。模型路由不得改变下方 S/M/L 流程深度。
 
-实现阶段由 brainstorming/writing-plans 以 `final/<需求名>.md` 为输入。
-本流程只产出需求(what/why),不做实现设计(how)。
+## 风险路由
+
+| 等级 | 判断 | 下一步 |
+|---|---|---|
+| S | 局部、可逆，不跨模块/数据/部署边界，验收明确 | 可直接实现并测试；不生成完整技术设计 |
+| M | 跨多个模块，或改变数据、公共接口、运行行为 | 执行 `feature-design`，生成精简技术设计 |
+| L | 改变系统边界、数据所有权、部署拓扑，或安全/迁移/可用性风险高 | 先更新项目基线，再执行完整 `feature-design`；只对未决高影响方案选择性使用 Superpowers |
+
+拿不准时选高一级，并在实现交接中写明原因。风险等级决定流程深度，不代表需求价值。
+
+## 外部行为契约边界
+
+只写调用方或用户可观察的承诺。不要在 final 需求中固定类、函数、表结构、队列、框架或部署组件，除非它们本身就是业务约束。

package/templates/common/docs/architecture/data-model.md

@@ -0,0 +1,43 @@
+# 数据模型基线
+
+> 项目：{{projectName}}
+> 最后更新：{{date}}
+> 先描述领域与数据语义；物理表、文档或消息结构只在已经确定时记录。
+
+## 适用性
+
+- 是否持久化数据：
+- 数据来源与权威源：
+
+## 核心实体
+
+| 实体 | 业务含义 | 标识与唯一性 | 所有者 | 生命周期 |
+|---|---|---|---|---|
+
+## 关系与约束
+
+- 实体关系：
+- 完整性约束：
+- 状态转换：
+
+## 一致性与并发
+
+- 一致性要求：
+- 并发冲突策略：
+- 幂等与去重：
+
+## 敏感数据与保留
+
+- 数据分类：
+- 访问与审计：
+- 保留、归档与删除：
+
+## 迁移与兼容
+
+- 初始化/迁移方向：
+- 前后兼容：
+- 回滚与校验：
+
+## 假设与开放问题
+
+- （每项附验证方式或复审条件）

package/templates/common/docs/architecture/deployment.md

@@ -0,0 +1,40 @@
+# 部署与运行基线
+
+> 项目：{{projectName}}
+> 技术栈：{{techStack}}
+> 最后更新：{{date}}
+
+## 环境与拓扑
+
+| 环境 | 部署单元 | 基础设施/外部依赖 | 状态位置 |
+|---|---|---|---|
+
+## 配置、密钥与权限
+
+- 配置来源与分环境策略：
+- 密钥存储与轮换：
+- 运行身份与最小权限：
+
+## 发布流程
+
+1. 构建与制品：
+2. 发布与验证：
+3. 数据迁移顺序：
+4. 回滚条件与步骤：
+
+## 运行保障
+
+- 存活与就绪判定：
+- 日志、指标、追踪和错误上报入口：
+- 告警与值守方式：
+- 备份、恢复目标与演练：
+
+## 容量与成本
+
+- 初始容量：
+- 扩缩容方式与触发条件：
+- 成本边界：
+
+## 单点、风险与开放问题
+
+- （每项附缓解措施或验证方式）

package/templates/common/docs/architecture/quality-attributes.md

@@ -0,0 +1,50 @@
+# 质量属性基线
+
+> 项目：{{projectName}}
+> 最后更新：{{date}}
+> 用可验证场景代替“高性能、可扩展、稳定”等形容词。
+
+## 负载与容量假设
+
+| 指标 | 当前/初始值 | 目标或上限 | 验证方式 | 复审触发条件 |
+|---|---|---|---|---|
+| 用户/租户数 | | | | |
+| 峰值吞吐 | | | | |
+| 数据规模与增长 | | | | |
+
+## 质量属性场景
+
+| 属性 | 场景与条件 | 系统响应 | 可量化指标 | 验证方式 |
+|---|---|---|---|---|
+| 性能 | | | | |
+| 可用性/可靠性 | | | | |
+| 安全性 | | | | |
+| 可维护性 | | | | |
+| 成本 | | | | |
+
+## 可观测性最低基线
+
+- 健康/就绪检查：
+- 结构化日志与关联 ID：
+- 核心流量、错误、耗时和饱和度指标：
+- 错误上报与部署版本：
+- 追踪适用条件：
+- 告警与运行手册：
+
+## 容量扩展性
+
+- 负载增长场景：
+- 当前瓶颈假设：
+- 水平/垂直扩容方向：
+- 状态、分区与背压：
+- 扩容触发指标：
+
+## 功能可扩展性
+
+- 预期变化场景：
+- 需要稳定的边界与兼容策略：
+- 明确不预留的抽象：
+
+## 假设与待验证项
+
+- （每项写明负责人、方式或复审条件）

package/templates/common/docs/architecture/system-context.md

@@ -0,0 +1,35 @@
+# 系统上下文
+
+> 项目：{{projectName}}
+> 最后更新：{{date}}
+> 状态：待建立基线
+
+## 目标与非目标
+
+- 目标：
+- 非目标：
+
+## 参与者与外部系统
+
+| 参与者/系统 | 关系 | 输入/输出 | 约束 |
+|---|---|---|---|
+
+## 系统边界
+
+- 系统负责：
+- 系统不负责：
+- 信任边界：
+
+## 模块与职责
+
+| 模块/部署单元 | 单一职责 | 依赖 | 状态归属 |
+|---|---|---|---|
+
+## 关键流程
+
+1. （写出跨边界的主路径和失败路径）
+
+## 决策、假设与风险
+
+| 类型（决策/假设/风险） | 内容 | 依据或验证方式 | 复审触发条件 |
+|---|---|---|---|

package/templates/common/docs/design/README.md

@@ -0,0 +1,22 @@
+# 功能技术设计目录
+
+- 按版本存放：`vX.Y.Z/<需求名>.md`。
+- 输入是 `docs/requirements/.../final/` 的需求定稿和 `docs/architecture/` 项目基线。
+- S 级需求可不生成完整设计；M/L 级按 `.ai/skills/feature-design.md` 执行。
+- 只记录 how 和相对项目基线的增量，不复述已确认的需求或整份架构基线。
+
+## 设计结构
+
+1. 目标与约束引用
+2. 风险等级与理由
+3. 现状及影响范围
+4. 模块、职责与依赖
+5. 技术接口契约
+6. 数据模型增量
+7. 核心流程与状态转换
+8. 错误、并发、幂等与兼容
+9. 质量属性增量
+10. 部署、迁移与回滚
+11. 测试与验证
+12. 假设和开放问题
+13. 交付验证（ready/conditional/not-ready、证据与阻塞项）

package/templates/common/docs/requirements/README.md

@@ -2,5 +2,6 @@
 
 - 每个迭代版本一个目录:`vX.Y.Z/`
 - `draft/` — 人工粗稿,自由格式,想到哪写到哪
-- `final/` — AI 协作定稿,固定结构:目标 / 范围 / 接口契约 / 验收标准 / 开放问题
+- `final/` — AI 协作定稿,固定结构:目标 / 范围 / 外部行为契约 / 验收标准 / 开放问题 / 实现交接
 - 定稿流程见 `.ai/skills/requirements-flow.md`(/new-requirement、/finalize-requirement)
+- how 阶段技术接口与数据/质量属性增量见 `.ai/skills/feature-design.md` 和 `docs/design/`