easy-coding-harness 0.1.8 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# 更新日志
+
+版本号严格使用 `x.y.z`：
+
+- `x`：大的功能迭代；`0.x.x` 表示内测版本
+- `y`：常规功能升级
+- `z`：日常 bug 修复
+
+## 0.3.0
+
+- 补充 `repository` / `homepage` / `bugs` 包元数据，并把 README 中的 CHANGELOG 链接改为 GitLab 绝对地址，修复 npm 页面相对链接跳转到 404 的问题。
+- README 改为使用导向说明，主线调整为安装、两阶段初始化、日常 `/ec-workflow` 入口、命令表、平台差异和真实 skill 清单。
+- MEMORY_LONG 门控改由 `easy_coding_state.py transition` 机械下发 `memory_long` 指令，避免短期记忆未超过阈值时被 prompt 误触发长期沉淀。
+- ec-memory 补充短期记忆消费后的删除步骤：成功蒸馏更早条目并更新长期索引后，删除已消费短期文件，仅保留最近 `short_term_keep` 条。
+- 实施 / 审查 / 验证三阶段统一强制子代理：IMPLEMENT 删除"主代理直接实现"分支，`single` / `sequential` / `parallel` 都派子代理（仅编排形态不同——单个串行执行也起子代理），保护主代理上下文不被实现细节污染；REVIEW / VERIFICATION 口径校齐，去掉"改动集大才派子代理"等矛盾表述。
+- 新增 `easy-coding update` 命令：更新全局 CLI 到最新发布版；存量项目仍按需单独执行 `easy-coding upgrade`。
+- 存量项目需要执行 `easy-coding upgrade` 才能拿到新的 hook 与 skill 模板。
+
+## 0.2.1
+
+- 新增 `easy_coding_state.py` 运行时状态 API，统一收口当前任务指针、任务状态、阶段流转、关闭/完成、`repo_paths` 等读写入口。
+- 修复状态栏卡在 Ready 的根因：状态栏继续由 hook 脚本注入，skill 不再手写 session/task 状态；hook 注入 session 文件路径供状态 API 精确写入。
+- 移除 tasks fallback / 最近任务猜测 / 自愈切换逻辑：session 为空时保持 Ready，任务进入 COMPLETE/CLOSED 后自动清空 `current_task`，不擅自切换到其他活跃任务。
+- 清理 `state.json` 新流程引用，保留其作为 legacy 迁移输入；新状态模型改为 `sessions/{ppid}.json` + `tasks/*/task.json` + 状态 API。
+- 修复 `easy-coding clear` 读取旧实验或损坏的 `install-manifest.json` 时，因 `agents` 字段缺失或损坏导致清理流程崩溃的问题；现在会安全降级并继续模板兜底清理。
+
+## 0.2.0
+
+- ec-analysis 新增防降级 HARD RULE：禁止把代码类任务（重构 / 修复 / 功能）擅自降级为"仅出报告 / 分析清单 / 留作后续子任务"。
+- 改动范围净化：只允许列真实项目源码 / 配置文件，禁止把 `.easy-coding/` 下的 dev-spec、execution、test-strategy、记忆、报告等 harness 产物当作改动对象。
+- 会话同步强化：dev-spec 完成后必须 Read 读回磁盘文件并原样回贴，禁止凭记忆缩略复述。
+- ec-workflow 在 INIT 阶段锁定交付形态，并在 ANALYSIS gate 呼应防降级与改动范围净化要求。
+- 澄清 `auto_mode` 语义：只免除 WAITING_CONFIRM 人工确认，不代表任何范围或交付形态决策。
+- README 将完整版本历史迁出到 CHANGELOG.md，并在 package.json `files` 中纳入 CHANGELOG.md，保证 npm 包内 README 引用有效。
+
+## 0.1.9
+
+- 记忆模板全面升级：MEMORY.md 新增 `memory_schema: 2` frontmatter、快速导航表格、读取策略和迁移审计表；BUSINESS.md 和 TECHNICAL.md 各增加 5 个分类表格和已淘汰记录区。
+- 新增 SHORT_MEMORY_TEMPLATE.md 短期记忆参考模板，包含完整 frontmatter schema（新增 `memory_schema`、`project_mode`、`commit`、`verification`、`memory_value` 字段）和 6 个结构化内容节。
+- 新增记忆迁移流程：ec-init 初始化时自动检测旧格式记忆（无 schema-v2 frontmatter、缺少 BUSINESS/TECHNICAL 文件），经用户确认后执行一次性迁移。
+- ec-memory 短期记忆格式强化：frontmatter 字段对齐原 Easy Coding 技能，新增文件命名规范和不可变约束。
+- ANALYSIS 阶段骨架优先规则加固：ec-workflow 转换规则、hook 面包屑、主约束文件、ec-analysis 顶部提醒四层强化。
+- 修复 .gitignore 误排 src/templates/、upgrade 缺少 sessions gitignore、主约束文件 marked-region 重复写入。
+- 拆分 `.easy-coding/config.yaml` 与 `.easy-coding/project.yaml`：CLI 独占结构配置，`ec-init` 独占项目语义配置，物理隔离 schema 分叉风险。
+- 新增 `easy-coding clear` 命令：移除已安装的 skills、hooks、agent 模板、CLI 配置和 sessions，保留 tasks、spec、memory、project.yaml 与项目知识文件。
+- 修复 `upgrade` 在 config.yaml 缺少 `harness_version` 时崩溃（`Cannot read properties of undefined (reading 'split')`）：版本比较源头防御 undefined，缺少 `harness_version` / `agents` 时明确引导 `easy-coding clear` 后重新 `init`。
+
+## 0.1.8
+
+- 状态重构：废弃全局 `state.json`，工作流阶段信息迁入 `task.json`。新增 per-session 文件（`.easy-coding/sessions/{ppid}.json`）隔离并行开发会话。
+- `task.json` 新增 `last_agent`、`stage_history`、`confirmed_by_user`、`test_strategy_confirmed`、`repo_paths` 字段，每次阶段转换实时更新 `status`。
+- 新增 `src/utils/session.ts` 模块，删除 `src/utils/state-json.ts`。
+- 强制子代理派发：IMPLEMENT（parallel 策略）、REVIEW、VERIFICATION 阶段使用 `<HARD-GATE>` 标记强制派发子代理，防止上下文污染。
+- 移除 REVIEW 阶段 ">=5 文件才派子代理" 的门槛，改为始终派发。
+- REVIEW auto-fix：bug 级问题由 ec-fixer 子代理直接修复，仅设计决策类问题才向用户确认。
+- 新增 ec-fixer 子代理模板（claude/codex/qoder 三平台）。
+- 修复 MEMORY_LONG 误触发：短期记忆 <= `memory.short_term_max`（默认 10）条时 MEMORY_LONG 为 no-op，仅超出阈值时执行蒸馏。
+- 新增状态机转换校验：hook 在每次 prompt 提交时验证阶段转换合法性，非法转换注入 `[ILLEGAL-TRANSITION]` 强警告。
+- session-start hook 自动检测并迁移旧格式 `state.json`，启动时清理 stale session 文件（>24h 且 PID 无占用）。
+
+## 0.1.7
+
+- ec-workflow 新增意图路由：用户带提示词进入时，自动匹配当前任务和已有任务，不匹配则询问切换或新建。
+- 支持任务切换：可在任何阶段挂起当前任务并切换到另一个任务，挂起任务的数据完整保留。
+- TaskJson 新增 `title` 可选字段，用于意图匹配和任务展示。
+- ec-task-management 任务创建和列表展示支持 title 字段。
+- CLI `easy-coding status` 命令在活跃任务列表中展示任务标题。
+- ec-brainstorming 设计确认后新增入口：询问用户是否立即创建任务，确认后自动衔接 ec-workflow 流程。
+- ec-analysis 新增 spec 文档扫描：自动读取 `.easy-coding/spec/` 下匹配的设计文档作为分析输入。
+- ec-analysis 新增 HARD RULES 强约束：首个 tool call 必须写 dev-spec.md 骨架文件，分析过程逐步回填，回复内容必须是 dev-spec.md 完整内容而非自创缩略格式。
+- 自检门禁增加文件存在性检查（dev-spec.md、execution.jsonl、test-strategy.md）和回复格式检查。
+- 修复 READY_LINE 引导用户使用 `ec-analysis` 启动任务的错误提示，改为 `ec-workflow`。
+- 同步修复 CLAUDE.md.tpl、AGENTS.md.tpl 主约束模板中的状态栏示例。
+
+## 0.1.6
+
+- ec-analysis 改为模板先行（template-first）工作流：分析阶段先创建 dev-spec.md 骨架，再逐步填充各章节。
+- ec-analysis 模板从英文简写替换为完整中文结构化模板，12 个核心必填章节 + 3 个条件展开章节。
+- 新增修订处理规则：用户修改意见必须重新输出完整方案，不允许只回差异摘要。
+- 自检门禁新增"占位符是否全部替换"检查项。
+- 测试策略补充人工验收和无法验证项。
+- 将版本记录从 CHANGELOG.md 迁移到 README.md 统一维护。
+- 新增项目级 CLAUDE.md 和 AGENTS.md 约束文件。
+
+## 0.1.5
+
+- ec-analysis 模板结构化改进：Change plan 改为五项一行式，Implementation units 输出完整 unit 表，Test strategy 内嵌 testability table + test points。
+
+## 0.1.4
+
+- 将宽终端 CLI banner 调整为 `ANSI Shadow` 厚重色块字形，恢复类似截图中的块状阴影质感。
+- 中等宽度终端使用 `Small Shadow`，窄终端继续使用 `Small Slant`，避免标题溢出。
+- 保留 0.1.3 的 cyan/blue 分层配色和副标题样式。
+- 修复主约束模板中状态栏示例使用外层双反引号，可能导致 agent 复述 Ready 状态栏时在末尾多带一个反引号的问题。
+
+## 0.1.3
+
+- 修复 0.1.2 CLI banner 字体过于块状、左右压缩导致难以辨认的问题。
+- 默认字体改为更舒展的 `Big`，中等宽度终端使用 `Doom`，窄终端继续使用 `Small Slant`。
+- 保留 0.1.2 的 cyan/blue 分层配色和副标题样式。
+- 将 hook 注入的 Easy Coding 状态提示收口为单行 Markdown 状态栏，展示 Ready、Waiting init、当前任务、任务状态和 handoff 来源。
+
+## 0.1.2
+
+- 改进 agent 平台选择提示，明确说明使用 Space 切换选择、Enter 进入确认。
+- 平台选择后增加二次确认，避免误按回车直接按默认平台安装。
+- 优化 CLI 启动标题，默认使用带阴影感的 `ANSI Shadow` 字体，并为窄终端提供 fallback。
+
+## 0.1.1
+
+- 修复 `easy-coding init` 将任意 `.easy-coding` 目录误判为已安装 harness 的问题。
+- 新增旧版 `easy-coding` skill 产物识别，允许在保留旧数据的前提下接入新 harness。
+- `project-init` 任务会记录旧资产清单，供 `ec-init` 校验、保留和补全旧数据产物。
+- 将 CLI 版本源统一到 `package.json`，避免源码常量与包版本漂移。
+
+## 0.1.0
+
+- 首个内测基线版本。
+- 提供 `easy-coding init`、`add-agent`、`upgrade`、`status` 基础命令。
+- 支持 Claude Code、Codex、Qoder 三个平台的 skills、hooks、agents 和主约束安装。

package/README.md

@@ -1,184 +1,158 @@
 # Easy Coding Harness
 
-把"AI 编码 Harness"一键安装到各 agent 平台标准目录的 CLI 脚手架。在项目里跑一次
-`easy-coding init`，按所选平台把 skills / hooks / 子代理 / 主约束文件写入平台标准目录，
-agent 原生识别——用 `/ec-`（Claude Code / Qoder）或 `$ec-`（Codex）即可调用。
+Easy Coding Harness 是一个 CLI 脚手架，用来把 Easy Coding 工作流安装到 Claude Code、Codex、Qoder 的原生目录。它只负责部署 skills、hooks、子代理、主约束文件和 `.easy-coding/` 运行时骨架，不分析项目代码；项目理解由安装后的 agent 通过 `ec-init` 完成。
 
-## 核心理念
-
-- **平台标准目录**：skills / hooks / agents 写进 `.claude/`、`.agents/` + `.codex/`、
-  `.qoder/`，复用 agent 已有的发现机制，不造新轮子。
-- **运行时 dead-drop**：`.easy-coding/` 存放 config / state / tasks / memory，所有产物
-  平台无关。换 agent、跨会话，信息零损失。
-- **约束即护城河**：8 阶段状态机 + 2 终态，WAITING_CONFIRM 与 VERIFICATION 是硬门控，
-  "没跑过的命令不算通过"。
+下文默认用 `/ec-*` 表示 Claude Code / Qoder 的触发方式；Codex 中对应使用 `$ec-*`。
 
 ## 安装
 
 ```bash
-# 方式一：源码（开发者 / 内网）
-git clone <repo> && cd easy-coding-harness && ./install.sh
+# 方式一：源码安装（开发者 / 内网）
+git clone <repo>
+cd easy-coding-harness
+./install.sh
+
+# 方式二：npm 正式环境（latest）
+npm install -g easy-coding-harness
+easy-coding --version
 
-# 方式二：npm beta（内测用户）
+# 方式三：npm beta 环境（内测用户）
 npm install -g easy-coding-harness@beta
 easy-coding --version
 ```
 
-两种方式都注册全局命令 `easy-coding`，效果一致。
+`0.x.x` 仍按内测版本管理时，优先使用 `easy-coding-harness@beta`；正式发布后使用默认 `latest` 安装命令。
 
-当前 `0.x.x` 版本为内测版本，npm 使用 `beta` dist-tag 发布。稳定版发布后，普通用户可使用
-`npm install -g easy-coding-harness` 安装默认 latest 版本。
+## 快速开始
 
-## 版本与更新日志
+1. 在目标项目根目录安装 harness 文件：
 
-版本号严格使用 `x.y.z`：
+```bash
+easy-coding init
+```
 
-- `x`：大的功能迭代；`0.x.x` 表示内测版本
-- `y`：常规功能升级
-- `z`：日常 bug 修复
+默认安装 Claude Code 支持。需要指定平台时：
 
-### 0.1.8
+```bash
+easy-coding init --agent=claude-code,codex,qoder
+```
 
-- 状态重构：废弃全局 `state.json`，工作流阶段信息迁入 `task.json`。新增 per-session 文件（`.easy-coding/sessions/{ppid}.json`）隔离并行开发会话。
-- `task.json` 新增 `last_agent`、`stage_history`、`confirmed_by_user`、`test_strategy_confirmed`、`repo_paths` 字段，每次阶段转换实时更新 `status`。
-- 新增 `src/utils/session.ts` 模块，删除 `src/utils/state-json.ts`。
-- 强制子代理派发：IMPLEMENT（parallel 策略）、REVIEW、VERIFICATION 阶段使用 `<HARD-GATE>` 标记强制派发子代理，防止上下文污染。
-- 移除 REVIEW 阶段 ">=5 文件才派子代理" 的门槛，改为始终派发。
-- REVIEW auto-fix：bug 级问题由 ec-fixer 子代理直接修复，仅设计决策类问题才向用户确认。
-- 新增 ec-fixer 子代理模板（claude/codex/qoder 三平台）。
-- 修复 MEMORY_LONG 误触发：短期记忆 <= `memory.short_term_max`（默认 10）条时 MEMORY_LONG 为 no-op，仅超出阈值时执行蒸馏。
-- 新增状态机转换校验：hook 在每次 prompt 提交时验证阶段转换合法性，非法转换注入 `[ILLEGAL-TRANSITION]` 强警告。
-- session-start hook 自动检测并迁移旧格式 `state.json`，启动时清理 stale session 文件（>24h 且 PID 无占用）。
+2. 打开目标 agent，运行项目知识初始化：
 
-### 0.1.7
+```text
+/ec-init
+```
 
-- ec-workflow 新增意图路由：用户带提示词进入时，自动匹配当前任务和已有任务，不匹配则询问切换或新建。
-- 支持任务切换：可在任何阶段挂起当前任务并切换到另一个任务，挂起任务的数据完整保留。
-- TaskJson 新增 `title` 可选字段，用于意图匹配和任务展示。
-- ec-task-management 任务创建和列表展示支持 title 字段。
-- CLI `easy-coding status` 命令在活跃任务列表中展示任务标题。
-- ec-brainstorming 设计确认后新增入口：询问用户是否立即创建任务，确认后自动衔接 ec-workflow 流程。
-- ec-analysis 新增 spec 文档扫描：自动读取 `.easy-coding/spec/` 下匹配的设计文档作为分析输入。
-- ec-analysis 新增 HARD RULES 强约束：首个 tool call 必须写 dev-spec.md 骨架文件，分析过程逐步回填，回复内容必须是 dev-spec.md 完整内容而非自创缩略格式。
-- 自检门禁增加文件存在性检查（dev-spec.md、execution.jsonl、test-strategy.md）和回复格式检查。
-- 修复 READY_LINE 引导用户使用 `ec-analysis` 启动任务的错误提示，改为 `ec-workflow`。
-- 同步修复 CLAUDE.md.tpl、AGENTS.md.tpl 主约束模板中的状态栏示例。
+`ec-init` 会让 agent 读取项目，生成 `.easy-coding/SOUL.md`、`.easy-coding/RULES.md`、`.easy-coding/ABSTRACT.md`、`.easy-coding/TEST_STRATEGY.md` 等项目知识文件。这个步骤幂等，重复运行是安全的。
 
-### 0.1.6
+3. 日常开发统一从工作流入口开始：
 
-- ec-analysis 改为模板先行（template-first）工作流：分析阶段先创建 dev-spec.md 骨架，再逐步填充各章节。
-- ec-analysis 模板从英文简写替换为完整中文结构化模板，12 个核心必填章节 + 3 个条件展开章节。
-- 新增修订处理规则：用户修改意见必须重新输出完整方案，不允许只回差异摘要。
-- 自检门禁新增"占位符是否全部替换"检查项。
-- 测试策略补充人工验收和无法验证项。
-- 将版本记录从 CHANGELOG.md 迁移到 README.md 统一维护。
-- 新增项目级 CLAUDE.md 和 AGENTS.md 约束文件。
+```text
+/ec-workflow 实现 xxx 功能
+```
 
-### 0.1.5
+`ec-workflow` 会创建或恢复任务，并按阶段调度分析、实现、审查、验证和记忆归档。
 
-- ec-analysis 模板结构化改进：Change plan 改为五项一行式，Implementation units 输出完整 unit 表，Test strategy 内嵌 testability table + test points。
+## 工作流
 
-### 0.1.4
+```text
+INIT -> ANALYSIS -> WAITING_CONFIRM -> IMPLEMENT -> REVIEW -> VERIFICATION
+                          ^                ^                      |
+                          |                +---- repair loop -----+
+                          +--- revision ---+                      |
+                                                        [user acceptance]
+                                                                  |
+                                          MEMORY_SHORT -> MEMORY_LONG -> COMPLETE
+any stage --[user abort via ec-task-close]--> CLOSED
+```
 
-- 将宽终端 CLI banner 调整为 `ANSI Shadow` 厚重色块字形，恢复类似截图中的块状阴影质感。
-- 中等宽度终端使用 `Small Shadow`，窄终端继续使用 `Small Slant`，避免标题溢出。
-- 保留 0.1.3 的 cyan/blue 分层配色和副标题样式。
-- 修复主约束模板中状态栏示例使用外层双反引号，可能导致 agent 复述 Ready 状态栏时在末尾多带一个反引号的问题。
+- `WAITING_CONFIRM` 是计划确认硬门控，未确认不进入实现。
+- `VERIFICATION` 是验证硬门控，未实际运行的 lint、typecheck、test 不算通过。
+- `MEMORY_SHORT` 写入本次任务短期记忆。
+- `MEMORY_LONG` 只有短期记忆数量超过阈值时才沉淀长期记忆，否则 no-op。
 
-### 0.1.3
+## CLI 命令
 
-- 修复 0.1.2 CLI banner 字体过于块状、左右压缩导致难以辨认的问题。
-- 默认字体改为更舒展的 `Big`，中等宽度终端使用 `Doom`，窄终端继续使用 `Small Slant`。
-- 保留 0.1.2 的 cyan/blue 分层配色和副标题样式。
-- 将 hook 注入的 Easy Coding 状态提示收口为单行 Markdown 状态栏，展示 Ready、Waiting init、当前任务、任务状态和 handoff 来源。
+| 命令 | 用途 |
+| --- | --- |
+| `easy-coding init` | 首次接入项目，安装所选平台的 skills、hooks、agents、主约束和运行时骨架 |
+| `easy-coding add-agent` | 给已接入项目追加 Claude Code、Codex 或 Qoder 支持 |
+| `easy-coding upgrade` | CLI 升级后同步项目内生成文件，生成区覆盖，用户资产保留 |
+| `easy-coding update` | 更新全局 CLI 到最新发布版 |
+| `easy-coding status` | 查看已安装平台、harness 版本、当前任务状态 |
+| `easy-coding clear` | 移除 harness 安装物，保留 tasks、spec、memory、project.yaml 等用户资产 |
 
-### 0.1.2
+## Skill 清单
 
-- 改进 agent 平台选择提示，明确说明使用 Space 切换选择、Enter 进入确认。
-- 平台选择后增加二次确认，避免误按回车直接按默认平台安装。
-- 优化 CLI 启动标题，默认使用带阴影感的 `ANSI Shadow` 字体，并为窄终端提供 fallback。
+### 流程 skills
 
-### 0.1.1
+| skill | 职责 |
+| --- | --- |
+| `ec-workflow` | 统一入口，负责任务创建、恢复、阶段流转和 stage skill 调度 |
+| `ec-brainstorming` | 实现前的设计探索和方案发散 |
+| `ec-analysis` | 生成 dev-spec、执行计划和测试策略 |
+| `ec-implementing` | 按确认后的计划执行代码实现 |
+| `ec-reviewing` | 多维度代码审查，输出 accept / fix / replan / blocked 结论 |
+| `ec-verification` | 执行 lint、typecheck、test 等验证硬门控，并处理验收修复循环 |
+| `ec-memory` | 写短期记忆，并在超过阈值时沉淀长期记忆 |
+| `ec-task-management` | 查看、创建、选择、恢复任务 |
+| `ec-task-close` | 用户主动中断任务并关闭 |
+| `ec-git` | 约束 git diff、commit、push、跨仓库提交等交付动作 |
+
+### 内置 skills
 
-- 修复 `easy-coding init` 将任意 `.easy-coding` 目录误判为已安装 harness 的问题。
-- 新增旧版 `easy-coding` skill 产物识别，允许在保留旧数据的前提下接入新 harness。
-- `project-init` 任务会记录旧资产清单，供 `ec-init` 校验、保留和补全旧数据产物。
-- 将 CLI 版本源统一到 `package.json`，避免源码常量与包版本漂移。
+| skill | 职责 |
+| --- | --- |
+| `ec-init` | 项目知识初始化和升级后的知识适配 |
+| `ec-meta` | 理解 harness 自身架构、平台文件和本地定制方式 |
 
-### 0.1.0
+## 平台支持
 
-- 首个内测基线版本。
-- 提供 `easy-coding init`、`add-agent`、`upgrade`、`status` 基础命令。
-- 支持 Claude Code、Codex、Qoder 三个平台的 skills、hooks、agents 和主约束安装。
+| 平台 | Skills 目录 | 触发符 | Hook 配置 | 主约束 |
+| --- | --- | --- | --- | --- |
+| Claude Code | `.claude/skills/` | `/` | `.claude/settings.json` | `CLAUDE.md` |
+| Codex | `.agents/skills/` | `$` | `.codex/hooks.json` | `AGENTS.md` |
+| Qoder | `.qoder/skills/` | `/` | `.qoder/settings.json` | `AGENTS.md` |
+| Qoder 中国版 | `.qodercn/skills/` | `/` | `.qodercn/settings.json` | `AGENTS.md` |
 
-## 命令
+同一份 skill 模板会在安装时根据平台替换 `{{placeholder}}`，因此日常使用遵循各平台自己的触发符和目录约定。
 
-| 命令 | 用途 |
-|------|------|
-| `easy-coding init` | 首次接入。`--agent=claude-code,codex,qoder` 选平台，`-y` 默认 claude-code |
-| `easy-coding add-agent` | 给已有项目追加平台支持 |
-| `easy-coding upgrade` | CLI 更新后同步项目里的功能文件（生成区覆盖，用户资产不动） |
-| `easy-coding status` | 查看已装平台、版本、当前任务状态 |
+## 升级
 
-## 两阶段初始化
+全局 CLI 更新后，已接入的项目需要在项目根目录执行：
 
-CLI 是纯文件搬运工，不做任何项目分析。初始化分两步：
+```bash
+easy-coding upgrade
+```
 
-1. **CLI** `easy-coding init` —— 装文件 + 建 `project-init` 占位任务。
-2. **Agent** `/ec-init` —— agent 分析代码，生成 SOUL / RULES / ABSTRACT / TEST_STRATEGY，
-   自动判断初创 vs 迭代项目。幂等，重复跑安全。
+`upgrade` 会刷新生成区内的 skills、hooks、agents、主约束模板和运行时模板，不会删除已有任务、spec、memory、project.yaml 或项目知识文件。
 
-之后日常工作统一走 `/ec-workflow`。
+## 版本与更新日志
 
-## 12 个 skill
+版本号使用 `x.y.z`：
 
-| skill | 职责 |
-|------|------|
-| ec-init | 项目知识初始化（幂等，一次性） |
-| ec-workflow | 工作流状态机 + 任务发现/恢复（日常入口） |
-| ec-brainstorming | 实现前设计探索（硬设计门，复刻 Superpowers 方法论） |
-| ec-analysis | 需求分析 + 执行计划 + 测试策略 |
-| ec-implementing | 编码实现 + 子代理并行调度 + 任务卡 |
-| ec-reviewing | 多维度审查（accept/fix/replan/blocked） |
-| ec-verification | 验证硬闸门 + 用户验收修复循环 |
-| ec-memory | 短期滑动窗口 + 长期记忆沉淀（schema v2） |
-| ec-task-management | 任务面板（创建 / 列表） |
-| ec-task-close | 任务中断与关闭 |
-| ec-git | git 操作约束 + 跨仓库提交 |
-| ec-meta | harness 自身架构理解 + 本地定制 |
-
-## 三平台支持
-
-| | Claude Code | Codex | Qoder |
-|---|---|---|---|
-| Skills 目录 | `.claude/skills/` | `.agents/skills/` | `.qoder/skills/` |
-| 触发符 | `/` | `$` | `/` |
-| Hook 配置 | `.claude/settings.json` | `.codex/hooks.json` | `.qoder/settings.json` |
-| 主约束 | `CLAUDE.md` | `AGENTS.md` | `AGENTS.md` |
-| 中国版 | — | — | `.qodercn/` |
-
-同一份 skill 模板，平台差异通过 `{{placeholder}}` 在安装时解析。
-
-## 工作流状态机
+- `x`：大的功能迭代；`0.x.x` 表示内测版本
+- `y`：常规功能升级
+- `z`：日常 bug 修复
 
-```
-INIT → ANALYSIS → WAITING_CONFIRM → IMPLEMENT → REVIEW → VERIFICATION
-                                        ↑                     │
-                                        └──── 修复循环 ────────┘
-                                                       [用户验收]
-                                        MEMORY_SHORT → MEMORY_LONG → COMPLETE
-任何阶段 ──[用户中断]──→ CLOSED
-```
+完整更新日志见 [CHANGELOG.md](https://gitlab.alibaba-inc.com/shixin.ysx/easy-coding-harness/-/blob/master/CHANGELOG.md)。
 
-## 开发
+## 开发者命令
 
 ```bash
 npm install
-npm run build      # tsup 编译 + 拷贝模板到 templates/
-npm test           # vitest
-npm run lint       # biome
+npm run build       # tsup 编译 + 拷贝 src/templates 到 templates/
+npm test            # vitest
+npm run lint        # biome check src/
+npm run typecheck   # tsc --noEmit
 ```
 
-源码结构：`src/commands/`（CLI 命令）、`src/configurators/`（平台配置器）、
-`src/templates/`（skills / hooks / 子代理 / 主约束模板）、`src/types/`（运行时数据契约）、
-`src/utils/`（文件写入 / 配置 / 分区替换等）。
+源码结构：
+
+| 目录 | 职责 |
+| --- | --- |
+| `src/commands/` | CLI 命令 |
+| `src/configurators/` | Claude Code、Codex、Qoder 平台安装器 |
+| `src/templates/` | skills、hooks、agents、主约束、运行时模板源 |
+| `src/types/` | 运行时状态和平台类型 |
+| `src/utils/` | 文件写入、配置、模板路径、gitignore、marked region 等工具 |