Edison（任务、QA、验证）

hstack 中的 Edison

本文档介绍如何结合使用 Edison 与 hstack 进行任务管理、QA、凭证收集和验证，并通过“栈 + 代码库工作树”实施严格的环境隔离。

如果只记住一条核心原则：

• 请使用 hstack edison ...（包装脚本），不要直接使用 edison ...
• 除非有充分理由，否则务必在指定的具名栈中运行 Edison 操作

一句话理解 Edison

Edison 是一个任务 + QA + 凭证 + 验证工作流层，具备角色提示词生成和可信凭证捕获能力。

在当前代码库中，Edison 不负责环境隔离；隔离完全由 hstack 提供。

本代码库的隔离模型

• 代码库工作树存放于 ⟦K16⟧/{dev,pr,local,tmp}/... 下
• 栈存放于 ~/.Kaiwu/stacks/⟦K17⟧/... 下，每个栈都拥有独立的端口、数据库、CLI 主目录等配置
• 本项目已禁用 Edison 的自带工作树（以避免与 hstack 工作树冲突）

实践建议：

• 切勿直接修改稳定检出分支（通常为 ⟦K18⟧/main）。
• 所有具体开发工作均应在 ⟦K19⟧/dev 或 ⟦K20⟧/{pr,local,tmp}/... 下的工作树中进行。
• 必须在正确的栈上下文中运行凭证捕获和验证。

唯一正确的入口点：hstack edison

切勿在此代码库中直接运行 edison ...。

请使用：

• hstack edison -- ⟦K21⟧
• hstack edison --stack=⟦K22⟧ -- ⟦K23⟧（推荐）

为什么必须使用该包装脚本：

• 加载正确的栈环境变量（Kaiwu_STACK_STACK + Kaiwu_STACK_ENV_FILE）
• 强制执行严格的故障闭锁（fail-closed）保护机制（确保匹配正确的栈和代码库工作树）
• 保证凭证捕获的确定性（记录栈所使用实际代码库检出的指纹）

参考文档：

• apps/stack/.edison/guidelines/**

会话（重点）

Edison 的“会话”概念依然存在，但在本代码库中，会话并未绑定到由 Edison 创建的 Git 工作树（工作树由 hstack 统一管理）。

请将会话视为：

• 归属与协同机制（“当前谁在处理什么任务”）
• 任务与 QA 状态的可选分组方式

当命令需要会话时，请显式传入（或在当前 Shell 中设置对应的会话环境变量）。

通常需要 vs 不需要会话的命令

本代码库的规范是：会话用于管理归属，而非负责隔离。

• 通常需要会话（涉及归属/生命周期）：
  • hstack edison -- task claim ⟦K24⟧ --session ⟦K25⟧
  • hstack edison -- task done ⟦K26⟧ --session ⟦K27⟧
• 通常不需要会话：
  • 凭证捕获：hstack edison --stack=⟦K28⟧ -- evidence capture ⟦K29⟧
  • 验证操作：hstack edison --stack=⟦K30⟧ -- qa validate ⟦K31⟧ --execute --preset ⟦K32⟧

注：具体的会话语义由 Edison 本身定义；如有疑问，可运行 hstack edison -- --help 查看。

任务模型（hstack）

我们采用严格的任务层级结构，以确保栈与工作树始终井然有序、不会被遗漏或遗忘。

• 父任务（hs_kind: parent）
  • 规划统筹项（不可认领）
• 轨道任务（hs_kind: track）
  • 独占绑定一个栈（stack: ⟦K33⟧）
  • 声明轨道（track: upstream|fork|integration）与作用域（components: [...]）
• 组件任务（hs_kind: component）
  • 轨道任务的子任务
  • 专门针对某一具体区域（component: ...）

注：此处的“组件”指单一代码仓库（monorepo）中的服务或包级作用域（如 apps/ui、apps/server、packages/*），并非独立的 Git 仓库。

功能规划（推荐工作流）

1) 查阅项目的“规划斜杠命令”

hstack edison -- read START_PLAN_FEATURE --type start

2) 创建父任务

hstack edison -- task new --id <id> --slug <slug>

接着编辑 .project/tasks/... 下新创建的文件，设置必填的 frontmatter 元数据：

• hs_kind: parent
• components: [...]

3) 自动搭建全部脚手架（推荐）

使用 hstack 包装脚本提供的脚手架辅助工具：

hstack edison task:scaffold <parent-task-id> --mode=upstream|fork|both --yes

该操作具备幂等性，并会尽可能自动完成以下事项：

• 创建轨道与组件子任务
• 为各个轨道创建栈
• 创建代码库工作树
• 将栈固定到对应的代码库工作树

推荐流程（开发实施）

1. 为该项工作创建或选择一个栈：

hstack stack new exp1
hstack stack wt exp1 -- use dev

2. 使用包装脚本执行 Edison 相关操作：

hstack edison --stack=exp1 -- <edison args...>

3. 捕获凭证并执行验证：

hstack edison --stack=exp1 -- evidence capture <task-id>
hstack edison --stack=exp1 -- qa validate <task-id> --execute --preset <preset>

注：hstack 可能会针对 qa validate --execute 强制执行预设策略。

凭证捕获与验证细节

凭证捕获

凭证应通过 Edison 捕获（基于快照机制，且能感知内容过期状态）：

hstack edison --stack=<stack> -- evidence capture <task-id> --preset <preset>

查看凭证详情：

hstack edison --stack=<stack> -- evidence status <task-id> --preset <preset>
hstack edison --stack=<stack> -- evidence show <task-id> --command <command-name>

验证预设（策略要求）

本代码库在执行验证时，通常要求显式指定预设：

hstack edison --stack=<stack> -- qa validate <task-id> --execute --preset <preset>

预设与策略规则位于 apps/stack/.edison/config/ 下。

Edison 存储路径说明

在本代码库中，Edison 配置随 hstack 一同提供，存放于：

• apps/stack/.edison/
  • config/（项目配置）
  • start/（角色提示词 / 斜杠命令）
  • templates/（任务/QA 模板）
  • packs/（项目专属逻辑）
  • validators/（验证器覆盖层/预设）

自动生成的内容（请勿手动编辑）：

• apps/stack/.edison/_generated/

本地任务/QA 状态（已被 gitignore 忽略）：

• .project/**

.project/ 下的关键约定目录：

• .project/tasks/{todo,wip,done,validated,blocked}/...
• .project/qa/...

自定义扩展点（如何安全修改行为）

• 项目配置：apps/stack/.edison/config/
• 项目模板（任务/QA 脚手架）：apps/stack/.edison/templates/
• 项目包逻辑（保护策略/规则）：apps/stack/.edison/packs/
• 指南与角色提示词：apps/stack/.edison/guidelines/ 与 apps/stack/.edison/start/

凭证与验证（正确操作指引）

推荐做法：始终在限定栈作用域下运行 Edison 凭证捕获与验证：

hstack edison --stack=dev -- evidence capture <task-id>
hstack edison --stack=dev -- qa validate <task-id> --execute

由于 hstack 会将栈所使用的代码库检出路径固定下来，因此这种方式能确保凭证结果的确定性。

高频运维命令

• 列出栈状态：hstack stack list、hstack stack info ⟦K34⟧
• 确保栈绑定到正确的代码检出路径：hstack stack wt ⟦K35⟧ -- use ⟦K36⟧
• 在编辑器中快速打开任务文件：打开 .project/tasks/.../⟦K37⟧.md

常见故障模式与应对策略

“栈不匹配” / “代码库检出路径错误”

解决方法：将栈重新绑定到目标检出分支：

hstack stack wt <stack> -- use dev

然后附带 --stack=⟦K38⟧ 参数重新运行 Edison 命令。

“验证被拒绝（必须指定预设）”

根据终端打印的提示信息，显式传入预设名称并重新运行：

hstack edison --stack=<stack> -- qa validate <task-id> --execute --preset <preset>

大语言模型（LLM）极简上手指南

1. 确认应使用的栈（高风险操作严禁使用 main）：

hstack stack list
hstack stack info dev

2. 确保该栈指向正确的检出分支/工作树：

hstack stack wt dev -- use dev

3. 所有 Edison 相关操作均使用包装脚本执行：

hstack edison --stack=dev -- <edison args...>