ECC Phase 1 问题工单包剖析：选择性安装、安装生命周期与会话适配契约的落地方案-二趣网

ECC Phase 1 问题工单包剖析：选择性安装、安装生命周期与会话适配契约的落地方案

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本指南基于 docs/PHASE1-ISSUE-BUNDLE-2026-03-12.md 这份规划文档展开，它为 GitHub 精选项目 ECC（Agent Harness Performance Optimization System）梳理了一批 Phase 1 落地任务：从"按 manifest 驱动的选择性安装"、"带 install-state 的安装生命周期（list-installed / uninstall / doctor / repair）"到"ECC 2.0 控制平面所需的规范化会话适配契约"与"生成/导入技能的去向与溯源策略"。读完本文，你将理解这些工单的来龙去脉——问题拆解、范围与非目标、验收标准——并看到它们与仓库内已有地基（manifests/install-profiles.json、schemas/install-state.schema.json、docs/SESSION-ADAPTER-CONTRACT.md 等）之间的一一对应关系。

背景：从"Mega Plan"到可执行 Issue Bundle

文档本身是一份"问题草案集合"（issue draft bundle）。它记录了 2026 年 3 月 11 日的 mega plan 与 3 月 12 日交接内容如何被整理成可投递到 GitHub 的工单正文，并保留了关键历史细节：

起草者最初尝试在 MCP 会话中直接创建 GitHub issue，因GitHub 认证缺失而被拦截；
之后通过ghCLI 成功投递，共 5 个工单：#423、#421、#424、#422、#425；
文档正文仅保存了其中 4 个完整工单（本地源 bundle），作为投递用正文的权威来源。

这种"先在仓库维护权威草稿、再投递到外部工单系统"的做法，本身就是一种可追踪的工程管理手段：Issue 正文的每次演进都有本地源码可供 diff 与审计。文档中也明确说明了 4 个工单与 GitHub 编号的对应关系，整理如下：

本地工单	GitHub Issue	标题	关注主题
Issue 1	#423	Implement manifest-driven selective install profiles for ECC	按配置/模块的选择性安装执行
Issue 2	#421	Add ECC install-state plus uninstall / doctor / repair lifecycle	安装状态与生命周期命令
Issue 3	#424	Define canonical session adapter contract for ECC 2.0 control plane	会话适配契约与快照
Issue 4	#422	Define generated skill placement and provenance policy	技能放置与溯源策略
（文档仅列标题）	#425	Define governance and visibility past the tool call	工具调用之后的治理与可见性

这四个工单共享一条主线：把 ECC 从"能装能用"推进到"可解释、可审计、可治理"。下面逐份展开。

Issue 1：基于 manifest 的选择性安装配置（#423）

问题本质：地基已就绪，缺的是"执行"

工单指出 ECC 的安装长期以来"按 target 与语言"进行（legacy 模式），尽管仓库已经具备首批选择性安装 manifest 与非变更式（non-mutating）计划解析器，但安装器本身还没有消费这些 profile。也就是说，问题不再出在"设计探索"，而在于把 profile/module 解析真正接入安装流程，同时保持向后兼容。

文档点名了当时已经落地的地基文件：

manifests/install-modules.json
manifests/install-profiles.json
scripts/ci/validate-install-manifests.js
scripts/install-plan.js

其中scripts/install-plan.js的核心角色正如其文件头注释所写："Inspect selective-install profiles and module planswithout mutating targets"——它是一个只读的"计划视图"，在写任何文件之前先回答"装什么、装到哪、跳过什么"。

Scope：为三种目标实现 manifest 驱动安装

工单明确本期执行范围为三个已支持的安装目标：claude、cursor、antigravity，并要求新增首轮 CLI 能力：

ecc-install --profile <name>：按命名 profile 解析并安装；
ecc-install --modules <id,id,...>：显式指定模块 ID 安装；
基于模块目标支持度的target-aware 过滤（目标不支持该模块则确定性跳过或拒绝）；
过渡期保持 legacy 语言模式安装的向后兼容。

Non-Goals：本期明确不做的事

工单刻意收敛范围，避免一次吞下太多：

不在同一 issue 中做完整 uninstall/doctor/repair 生命周期（留给 Issue 2）；
若阻碍发布，Codex/OpenCode 安装目标不做进首轮（当前仓库 manifest 里opencode、codex等目标已扩展，说明这是后续的演进结果）；
不把仓库重组成多个独立发布包。

验收标准：可验证的安装行为

工单给出 6 条验收标准，翻译成可测试断言即：

install.sh能解析并安装一个具名 profile；
install.sh能解析显式模块 ID；
目标不支持的模块被确定性跳过或拒绝；
legacy 语言安装模式仍然可用；
测试覆盖 profile 解析与安装器行为；
文档解释新的推荐 profile/module 安装路径。

仓库现状：manifest 背后的真实结构

理解这个工单，关键是看清 profile 与 module 两层数据结构。当前 manifests/install-profiles.json 定义了多个具名 profile，例如：

minimal：面向低上下文 Claude Code 场景，包含 rules/agents/commands/platform-configs/workflow-quality，不含 hook runtime；
core：最小编制的 harness 基线，在上述基础上加hooks-runtime；
developer：面向大多数应用代码库场景的默认工程 profile，在 core 上叠加 framework-language、database、orchestration 等；
security：安全侧重配置；
research：研究与内容创作场景（research-apis、business-content、social-distribution 等）；
full：当前已分类模块的全量安装。

而 manifests/install-modules.json 为每个模块声明了id、kind（rules/agents/commands…）、描述、paths（该模块拥有哪些相对路径）、targets（支持哪些目标）、dependencies、defaultInstall、cost与stability。例如rules-core的paths为["rules"]，支持claude、cursor、antigravity等十余个目标；commands-core则把commands目录以及scripts/harness-audit.js、scripts/skills-health.js两个脚本收进同一模块。可见"target-aware 过滤"在 manifest 层就已经有了数据基础。

scripts/install-plan.js在命令行层将这些数据暴露给用户，常用形式为：

node scripts/install-plan.js --list-profiles # 列出所有 profile node scripts/install-plan.js --list-modules # 列出所有模块 node scripts/install-plan.js --profile developer # 解析 developer profile 的计划 node scripts/install-plan.js --modules rules-core,commands-core --target claude node scripts/install-plan.js --config <path> # 从 ecc-install.json 读取安装意图 node scripts/install-plan.js --profile core --without hooks-runtime --json

其中--json输出机器可读的计划，供上层安装器或 CI 消费；--with / --without允许在 profile 基础上做增量微调；--skills <skill-id>会把技能组件以skill:<id>前缀纳入解析。计划解析背后由 scripts/lib/install-manifests.js 的resolveInstallPlan承担，并与 scripts/lib/install/request.js 的normalizeInstallRequest协同——先把原始请求规范化成"profile + modules + include/exclude components + legacy 语言"的统一结构，再做模块筛选。

Issue 2：install-state 与 uninstall / doctor / repair 生命周期（#421）

问题本质：没有"安装状态记录"，生命周期全靠猜

工单的核心论断非常精炼：ECC 没有规范化的已安装状态记录（installed-state record），导致卸载、修复与安装后检查都不确定。仓库虽然能对"可安装内容"分类，却无法可靠回答四个问题：

装的是什么 profile / 哪些模块；
装进了哪个 target；
ECC 拥有哪些路径；
如何只移除或修复 ECC 管理的文件。

一旦缺少 install-state，"生命周期命令就只是猜测"（lifecycle commands are guesswork）。

Scope：引入持久化 install-state 契约与首批生命周期命令

工单规划了四个命令，正好对应仓库根目录下的四个可执行脚本：

ecc list-installed→ scripts/list-installed.js
ecc uninstall→ scripts/uninstall.js
ecc doctor→ scripts/doctor.js
ecc repair→ scripts/repair.js

工单还给出了建议的 state 存放位置（按 target 区分）：

Claude：~/.claude/ecc/install-state.json（home 级）
Cursor：./.cursor/ecc-install-state.json（项目级）
Antigravity：./.agent/ecc-install-state.json（项目级）

state 文件至少需要捕获：安装版本、时间戳、target、profile、解析后的模块列表、复制/管理的路径、以及来源仓库版本或包版本。

Non-Goals：避免推倒重来

不从零重建安装器架构；
不做完整远程/云端控制面功能；
除自然演进外，不扩展本地安装器之外的目标支持。

验收标准

成功的安装确定性地写入 install-state；
list-installed能干净地报告 target/profile/modules/version；
doctor报告缺失或漂移（drifted）的管理路径；
repair依据记录的 install-state 恢复缺失的管理文件；
uninstall只移除 ECC 管理的文件，不碰无关本地文件；
测试覆盖 install-state 创建与生命周期行为。

仓库现状：install-state 契约已经落地

这条验收标准的"确定性"在仓库中被翻译成了 JSON Schema：schemas/install-state.schema.json。它定义了ecc.install.v1契约，顶层必填字段为：

schemaVersion（固定ecc.install.v1）；
installedAt（以及可选的lastValidatedAt）；
target：id、root、installStatePath，且kind只能是home或project——这正好印证工单里"home 级 vs 项目级"两种 state 位置设计；
request：完整记录用户的安装请求，包括profile（可为 null）、modules、includeComponents、excludeComponents、legacyLanguages、legacyMode布尔与可选的hookConsent；
resolution：selectedModules与skippedModules两个数组——这让"哪些模块被选中、哪些被跳过"在事后依然可审计；
source：repoVersion、repoCommit、manifestVersion，实现工单要求的"来源仓库版本或包版本"；
operations：逐条记录复制/写入操作，每条含kind、moduleId、sourceRelativePath、destinationPath、strategy、ownership、scaffoldOnly，可选contentSha256（64 位十六进制），从而精确圈定"ECC 拥有哪些路径"。

也就是说，"路径所有权"在 schema 层通过每个 operation 的ownership字段显式声明，这为uninstall只删 ECC 管理文件、repair按 operation 重建、doctor比对文件是否存在提供了结构化依据。运行实现则集中在 scripts/lib/install-lifecycle.js，例如discoverInstalledStates与uninstallInstalledStates分别支撑 list 与 uninstall。

list-installed.js的人类可读输出按 adapter 列出Root、Installed时间、Profile（legacy/custom 时标注）与Modules，并支持--target与--json；uninstall.js还额外处理了 legacy 的sync-ecc-to-codex.sh制品，仅在存在 legacy 所有权清单时清理，必要时用--legacy-codex-sync强制走 legacy 路径，并支持--dry-run先演练再动手——这与验收标准中"只移除 ECC 管理的文件"一脉相承。

Issue 3：ECC 2.0 控制平面的规范会话适配契约（#424）

问题本质：编排已有，但都是"实现特化"

工单描述的现状分层很清晰：

tmux/worktree 编排已存在；
机器可读的会话快照已存在；
Claude 本地会话历史命令已存在；

但缺少的是一个harness 无关的适配边界（adapter boundary），用来把以下会话/任务来源归一化：

tmux 编排的 workers；
普通 Claude 会话；
Codex worktrees；
OpenCode 会话；
未来的远程或 GitHub 集成操作面。

如果不定义这个契约，任何未来的 ECC 2.0 operator shell 都只能被迫直接读取 tmux 专属与 markdown 协调细节。

Scope：首批适配层交付物

adapter 注册表（registry）；
规范会话快照 schema；
由现有编排代码支撑的dmux-tmuxadapter；
由现有会话历史工具支撑的claude-historyadapter；
用于检查规范快照的只读 inspection CLI。

Non-Goals

不在同一 issue 内做完整 ECC 2.0 UI；
不做商业化 / GitHub App 实现；
不做远程多用户控制面。

验收标准

有文档化的规范快照契约；
现有 tmux 编排快照代码被包装为 adapter，而不是继续充当顶层产品契约；
存在第二个非 tmux adapter，以证明抽象是真实的；
测试覆盖 adapter 选择与规范化快照输出；
设计清晰区分 adapter 关注点与编排、UI 关注点。

仓库现状：`ecc.session.v1`契约与实现

这条验收标准在仓库里同样有明确落点。docs/SESSION-ADAPTER-CONTRACT.md 就是规范文档，声明规范快照契约为ecc.session.v1，并以 scripts/lib/session-adapters/canonical-session.js 为实现与消费者的规范来源。

契约规定：每个 adapter 必须返回一个可 JSON 序列化的对象，顶层形状固定为：

{ "schemaVersion": "ecc.session.v1", "adapterId": "dmux-tmux", "session": { "id": "workflow-visual-proof", "kind": "orchestrated", "state": "active", "repoRoot": "/tmp/repo", "sourceTarget": { "type": "session", "value": "workflow-visual-proof" } }, "workers": [ { "id": "seed-check", "label": "seed-check", "state": "running", "health": "healthy", "branch": "feature/seed-check", "worktree": "/tmp/worktree", "runtime": { "kind": "tmux-pane", "command": "codex", "pid": 1234, "active": false, "dead": false }, "intent": { "objective": "Inspect seeded files.", "seedPaths": ["scripts/orchestrate-worktrees.js"] }, "outputs": { "summary": [], "validation": [], "remainingRisks": [] }, "artifacts": { "statusFile": "/tmp/status.md", "taskFile": "/tmp/task.md", "handoffFile": "/tmp/handoff.md" } } ], "aggregates": { "workerCount": 1, "states": { "running": 1 }, "healths": { "healthy": 1 } } }

从这个快照结构可以读出设计意图：runtime.kind（如tmux-pane）只是 worker 运行时细节，被归入一个字段而非顶层；health与state是归一化后的业务语义；aggregates让控制面无需遍历所有 worker 即可得到聚合视图。这样无论底层是 tmux pane、Codex worktree 还是未来远程会话，上层 UI/operator shell 读到的都是同一套字段，正好兑现工单"不再直接读 tmux 细节"的目标。

Issue 4：生成技能的去向与溯源策略（#422）

问题本质：技能面在增长，策略没跟上

工单点出 ECC 的技能面（skill surface）已经"大且持续增长"，但生成（generated）/导入（imported）/学习（learned）的技能缺少清晰的长期放置与溯源策略，进而引发四类问题：

策展技能（curated）与生成/学习技能之间边界不清；
校验器对"本地可能有也可能没有"的目录产生噪声；
导入或机器生成内容的溯源薄弱；
未来自动化学习产物的存放位置不确定。

仓库中skills/下既有大量手动维护的 SKILL.md，又有 agent-self-evaluation、continuous-learning-v2、rules-distill、skill-stocktake 这类会产出学习结果或自动生成内容的技能目录，这正是工单所述矛盾的直接背景。

Scope：定义仓库级策略

策展 vs 生成 vs 导入技能的放置规则；
溯源元数据要求；
校验器对可选/生成目录的行为；
生成技能是随包发布、被 ignore、还是在 install/build 步骤中物化（materialize）。

Non-Goals

不做完整的外部技能市场；
不一次性重写全部现有技能内容；
不试图在同一 issue 解决所有内容质量问题。

验收标准

存在文档化的生成/导入技能放置策略；
溯源要求明确；
校验器不再对可选/生成技能位置产生含糊行为；
策略清楚说明什么可发布、什么仅本地；
后续实现工作被拆分为具体、有界的 PR 级步骤。

仓库现状：溯源 Schema 与放置政策的落实

当前 docs/SKILL-PLACEMENT-POLICY.md 已把工单的验收要求展开为具体规则，可归纳为以下分层：

技能类别	来源	溯源要求
策展技能	ECC 仓库直接维护	通过`SKILL.md`frontmatter 的`origin`（如 ECC、community）标注归属，无单独 provenance 文件
学习/演进技能	evaluate-session、/learn、instinct evolve 等自动产出	必须有与`SKILL.md`同级的`.provenance.json`
导入技能	URL、文件复制等外部来源	必须有与`SKILL.md`同级的`.provenance.json`
本能导出（instincts）	由源 instinct 继承而来	溯源从源继承，无需单独`.provenance.json`

策略文件还给出了实现链路的精确指针：溯源 schema 定义在 schemas/provenance.schema.json，校验逻辑在scripts/lib/skill-evolution/provenance.js的validateProvenance；并规划了分批落地步骤——先落策略与 schema，再把溯源校验接入 learned-skill 写入路径，接着让 instinct-cli evolve 写入可选溯源，最后视需要把scripts/validate-provenance.js接入 CI。

值得注意的是第 5 个工单（#425，Define governance and visibility past the tool call）在文档的 GitHub 状态列表中列出，但其正文未包含在本地 bundle 内。从主题看它与上述四份工单方向一致：都指向"工具调用（安装、执行、生成）之后如何治理、如何可见"这一 Phase 1 的总体目标。

四份工单的共性方法论

把这四份 issue 放在一起，可以看到 ECC 团队处理"平台级演进"时反复使用的一套可复用方法，这对任何希望用 issue 驱动重构的仓库都有借鉴价值：

先盘点已落地地基，再定义缺失步骤。Issue 1 明确说"missing step is no longer design discovery... missing step is execution"；Issue 2 列出现有分类能力；Issue 3 列出 tmux/快照/历史命令三个已有事实。这避免了重复造轮子，也让 issue 的"剩余工作量"边界清晰。
每条验收标准都可测试、可演示。四份工单的验收标准几乎都能翻译成 shell 命令 + 断言：解析 profile、写入 state、报告 drift、恢复文件、输出归一化快照、生成 provenance 文件。
范围控制靠 Non-Goals 显式声明。每份工单都写下"本期不做"清单，防止把市场、UI、远程控制面等大主题卷进小迭代。
设计契约先于产品实现。Issue 3 专门要求"第二个非 tmux adapter 证明抽象真实"，并用ecc.session.v1schema、ecc.install.v1schema、provenance.schema.json这类版本化 JSON 契约把"约定"固化为可校验文件。

企业官网建设流程全解析