work-ally 0.2.0-alpha.1

package/docs/planning/SPEC-approval-rules-inheritance-and-local-validation-lane.md

@@ -0,0 +1,450 @@
+# SPEC: Approval Rules Inheritance And Local Validation Lane
+
+更新时间：2026-03-22  
+状态：Ready for review  
+Owner：work-ally product / engineering  
+相关文档：
+- `docs/completed/SPEC-approval-autonomy-and-safe-defaults.md`
+- `docs/planning/SPEC-bridge-app-server-protocol-alignment.md`
+- `AGENTS.md`
+- `README.md`
+
+## 1. Summary
+
+这次要解决的不是“审批卡文案还可以更顺一点”，而是把 `work-ally` 的审批机制补到一个长期可用的产品基线。
+
+当前真实问题已经很明确：
+
+1. assistant 在当前项目内做连续本地验证时，仍会反复把 `cmake`、`ctest`、shell 包裹的本地编辑/验证命令抛给用户审批。
+2. 官方 Codex 已经提供了按命令前缀记住放行决策的 `.rules / prefix_rule` 机制，但 `work-ally` 还没有把这层能力接进自己的审批链路。
+3. 结果就是：用户已经明确放行过一类动作，下一次还是要继续在 Feishu 里回 `OK / 同意`，工作流被大量低价值确认打断。
+4. 对已经在官方 Codex 里做了很久的项目来说，全局 `~/.codex/rules/*.rules` 本身已经沉淀了大量历史放行资产；如果 `work-ally` 不持续继承这层资产，而是让用户重新从零审批，会造成明显的产品割裂。
+
+本次 feature 要同时做两件事：
+
+1. **兼容并复用官方 Codex 的 `.rules` 规则机制**，让“按前缀记住放行/拒绝”这件事在 `work-ally` 里真正生效。
+2. **扩大本地低风险验证 lane**，把当前项目根 / assistant desk 根内的 build、test、lint、诊断类命令纳入默认自治边界，不再继续要求用户逐条拍板。
+
+一句话定义：
+
+> 用户只需要为真正的风险边界拍板；已经记住的前缀规则和明确属于本地低风险验证的动作，`work-ally` 应自动匹配并自动处理，而不是继续把用户拉进 assistant 的内部自测过程。
+
+## 2. 背景
+
+### 2.1 真实日志已经说明问题不是个例
+
+2026-03-22 的 `Matrix` assistant 日志里，单日出现了至少 30 次命令审批；其中 17 次集中在同一条 turn 内。
+
+主要类型包括：
+
+- `python3 <<'PY'` 的本地仓库编辑命令
+- `cmake -S/-B`
+- `cmake --build`
+- `ctest --test-dir ...`
+- 相关 git 环境准备命令
+
+这说明问题不是“偶尔会多问一次”，而是当前审批边界和自动放行策略都还不够产品化。
+
+### 2.2 现有自治白名单过窄
+
+当前 shipped 基线已经做了一轮审批收口：
+
+- 当前项目根 / assistant desk 根内的文件写入可自动放行
+- 一小部分低风险命令可自动放行，例如 `git status/diff/add/commit`、`npm test`、`node --test`、`bash tests/shell/*.sh`
+
+但这条白名单明显还停留在 `work-ally` 自己常用的维护路径上，没有覆盖更一般的本地 build / test / validation 工作流。
+
+结果是：
+
+- `cmake` / `ctest` 这类非常典型的本地验证命令仍然要审批
+- shell 包裹的本地多段验证命令仍然要审批
+- 用户已经认可“这类事可以审批”，但体验上仍被连续打断
+
+### 2.3 官方 Codex 已有 remembered-prefix 能力
+
+官方 Codex 现在已经有 `.rules` 机制，可以通过 `prefix_rule(pattern=[...], decision="allow|prompt|forbidden")` 记住一类命令前缀的处理策略。
+
+这意味着：
+
+- `work-ally` 没必要重新发明一套新的规则文件格式
+- 用户对官方 `.rules` 的已有理解和资产应尽量直接复用
+- 如果 middle layer 还忽略这层能力，就会造成“官方能记住，接进 work-ally 反而记不住”的体验倒退
+
+这里还有一个关键产品判断必须明确：
+
+- `~/.codex/rules/*.rules` 应被视为用户在 Codex 生态里的**持续生效事实源**
+- 它不应只在 assistant 创建时被复制一次后就与 `work-ally` 分家
+- 否则同一个项目一旦从官方 Codex 切到 Feishu / work-ally，就会重新冒出大量本已放行过的审批请求
+
+## 3. 问题定义
+
+当前问题有四层。
+
+### 3.1 同类本地低风险动作仍在重复审批
+
+用户已经接受“高风险动作走审批”，但无法接受一天里对几十条同类 build/test/编辑命令重复回同意。
+
+这会把用户从“负责人”降级成“按钮操作员”。
+
+### 3.2 `work-ally` 还没接住官方规则资产
+
+即使用户已经在官方 Codex 里使用 `.rules` 或未来希望沿用同样的 mental model，当前 `work-ally` 也不会在 bridge 收到 approval request 时去匹配这些规则。
+
+结果就是：
+
+- 官方规则和 `work-ally` 规则割裂
+- assistant 专属 `CODEX_HOME` 与全局 `~/.codex` 的规则资产没有形成一致产品语义
+
+### 3.3 规则记忆与本地安全默认值是两套机制，但目前只做了半套
+
+低风险本地验证 lane 和 `.rules` 前缀记忆并不是互斥关系。
+
+- 本地安全默认值解决的是“这类动作本来就不值得打断用户”
+- `.rules` 解决的是“即便默认不自动放行，用户放行过一次后，后续该能按前缀记住”
+
+当前只做了很窄的一层默认自治，没有接入规则记忆，所以两边都不完整。
+
+### 3.4 assistant 本地规则落点还没产品化
+
+官方规则机制支持全局规则，但 `work-ally` 的多 assistant 产品模型还需要一个额外判断：
+
+- 这次“记住”应该写到全局还是 assistant 本地？
+
+如果不拍板，后续实现就会漂移。
+
+### 3.5 规则继承如果做成“创建时复制”，会让体验割裂
+
+如果 `work-ally` 只是 assistant 创建时把全局 rules 拷一份到本地，会出现三个问题：
+
+1. 用户之后在官方 Codex 新增的放行规则，`work-ally` 看不到。
+2. 用户之后修改或撤销的全局规则，`work-ally` 仍在沿用旧快照。
+3. 同一个项目在官方 Codex 和 Feishu / work-ally 之间切换时，会表现得像两套互不连通的授权世界。
+
+因此，“创建时复制一份”不是可接受方案。
+
+## 4. 目标 / 非目标
+
+### 4.1 目标
+
+1. 让 `work-ally` 在命令审批链路里兼容官方 `.rules / prefix_rule` 规则语法。
+2. 支持同时读取全局 `~/.codex/rules/*.rules` 与 assistant 本地 `<assistant-codex-home>/rules/*.rules`。
+3. 明确全局 `~/.codex/rules/*.rules` 是持续继承的事实源，而不是 assistant 创建时的一次性初始化快照。
+4. 在收到 runtime command approval 后，先按规则决定 `allow / prompt / forbidden`，再决定是否向用户发审批卡。
+5. 扩大本地低风险验证 lane，把当前项目根 / assistant desk 根内的典型 build / test / lint / diagnostics 命令纳入默认自治边界。
+6. 将“记住这次放行”的默认落点拍板为 assistant-local rules，而不是默认污染全局 rules。
+7. 保持 archive / timeline 可审计：自动放行、规则命中、规则拒绝都要留下稳定记录。
+
+### 4.2 非目标
+
+1. 本次不做新的远程规则同步系统。
+2. 本次不做独立的规则编辑 UI 或审批面板。
+3. 本次不支持完整重现官方所有 experimental rules 特性；只实现 `work-ally` 审批链路真正需要的稳定子集。
+4. 本次不把所有本地命令一律自动放开。
+5. 本次不修改 MCP tool approval 的已有 allowlist 设计；那条链路继续保留。
+
+## 5. 为什么它不是 Skill
+
+这次是 `Core`，不是 Skill。
+
+原因：
+
+1. 它直接改变 `work-ally` 的审批语义、默认行为和用户路径。
+2. 它作用于 bridge 主链路，是 runtime request 到用户可见审批之间的核心合同。
+3. 如果把它做成 Skill，就会导致“某个 Skill 在决定 bridge 是否发审批卡”，这会破坏核心边界。
+
+因此本专题必须留在 core。
+
+## 6. 产品定义与用户路径
+
+### 6.1 一句话定义
+
+`work-ally` 的命令审批默认流程应变成：
+
+1. 先看它是不是本地低风险验证动作；如果是，静默自动放行。
+2. 否则再看是否命中 `.rules`；这里的 `.rules` 包括持续继承的全局 rules 和 assistant-local rules。命中 `allow` 就自动放行，命中 `forbidden` 就自动拒绝。
+3. 只有既不属于低风险自治 lane、也没有命中 remembered rules 的动作，才真正向用户发审批卡。
+
+### 6.2 主路径 A：本地低风险验证动作
+
+场景：assistant 在当前项目根或 assistant desk 根内运行 build / test / lint / diagnostics。
+
+路径：
+
+1. runtime 发出 command approval request。
+2. bridge 判断该命令属于本地低风险验证 lane。
+3. 直接向 runtime 回写 `accept`。
+4. 不向用户发送审批卡。
+5. 在 archive / timeline 记录 `approval_auto_resolved`，附带 `policy = local_self_validation` 或更细的 lane 原因。
+
+### 6.3 主路径 B：命中 remembered allow rule
+
+场景：某类命令不在默认自治白名单里，但用户之前已经明确允许过相同前缀。
+
+路径：
+
+1. runtime 发出 command approval request。
+2. bridge 按规则文件匹配到 `allow`。
+3. 直接向 runtime 回写 `accept`。
+4. 不向用户发送审批卡。
+5. 记录 `approval_auto_resolved`，`policy = rules_allow`，并带 `matched_rule`。
+
+### 6.4 主路径 C：命中 remembered forbidden rule
+
+场景：某类命令前缀已被规则标记为禁止。
+
+路径：
+
+1. runtime 发出 command approval request。
+2. bridge 匹配到 `forbidden`。
+3. 直接向 runtime 回写 `decline`。
+4. 不向用户发送审批卡。
+5. assistant 继续收到 runtime 的拒绝后果，前台只看到必要的失败结果或解释，不额外再发一张“要不要批准”卡。
+
+### 6.5 主路径 D：未命中规则，且不在低风险自治 lane
+
+场景：高风险、跨边界、未知命令。
+
+路径：
+
+1. runtime 发出 command approval request。
+2. bridge 先判断本地自治 lane，未命中。
+3. 再匹配规则文件，也未命中。
+4. 正常向用户发审批卡。
+
+### 6.6 规则写入路径
+
+先明确 V1 边界：
+
+- V1 **不**在 Feishu 审批卡里提供“记住这次放行/拒绝”的前台写入入口。
+- V1 先只做 rules 的读取、继承、匹配和自动处理，把“历史授权延续”这件事先收住。
+- assistant-local rules 的默认写入路径先作为后续产品约束拍板，不要求本期就把前台入口做出来。
+
+当后续版本引入“记住这次放行/拒绝”类动作授权时：
+
+1. 默认写入 assistant 本地 `<assistant-codex-home>/rules/default.rules`。
+2. 不默认写入全局 `~/.codex/rules/default.rules`。
+3. 只有明确的全局管理动作，才允许修改全局规则。
+
+产品判断：
+
+- assistant 是按项目长期驻留的，规则记忆默认也应跟 assistant 走。
+- 全局 rules 仍可被持续读取并生效，但不应被普通日常审批顺手污染。
+
+### 6.7 规则继承语义
+
+必须明确：
+
+1. `work-ally` 对全局 `~/.codex/rules/*.rules` 的使用是**持续继承**，不是“创建 assistant 时复制快照”。
+2. assistant 创建、绑定或重启后，仍应看到最新的全局 rules 变化。
+3. assistant-local rules 是增量覆盖层，不是全局 rules 的替代副本。
+
+产品语义上，这意味着：
+
+- 用户在官方 Codex 里已经放行过的前缀授权，不应因为切到 Feishu / work-ally 就失效。
+- 用户后来新增、修改或撤销的全局规则，也应在 `work-ally` 里继续反映出来。
+
+## 7. 机制设计
+
+### 7.1 规则源与事实层级
+
+V1 读取两层规则：
+
+1. 全局规则目录：`~/.codex/rules/`
+2. assistant 本地规则目录：`<assistant-codex-home>/rules/`
+
+读取规则：
+
+- 只关心 `*.rules`
+- 按文件名稳定排序后加载
+- assistant 本地规则优先级高于全局规则
+- 全局规则目录不是 assistant 创建时的模板来源，而是运行时持续继承的事实源
+
+理由：
+
+- 全局 rules 适合个人通用偏好
+- assistant 本地 rules 适合项目/助理特定偏好
+- 本地应能覆盖全局，而不是反过来
+- 只有把全局 rules 当持续事实源，而不是 copy-on-create 快照，才能避免官方 Codex 与 work-ally 两边授权历史割裂
+
+### 7.1.1 加载时机
+
+实现目标不是“每次审批都重新扫磁盘”，而是“语义上持续继承”。
+
+V1 可接受的实现方式：
+
+1. bridge / runtime 启动时加载当前全局 + assistant-local rules。
+2. assistant 重启后必须重新看到最新的全局 rules。
+3. V1 **不要求**运行中的 bridge 在用户改动全局 rules 后立即热生效；只要求 assistant 重启后必须继承最新变化。
+4. 如后续成本允许，可再补简单热重载或基于 mtime 的刷新；但无论如何，不能退化成 assistant 创建时复制一份后长期脱钩。
+
+这条要求的重点是产品语义：
+
+- **允许缓存**
+- **V1 允许“运行中不热更新，但重启后更新”**
+- **不允许 copy-on-create 分叉**
+
+### 7.2 支持的规则子集
+
+V1 只支持 `prefix_rule`：
+
+- `pattern=[...]`
+- `decision="allow" | "prompt" | "forbidden"`
+
+不支持的语法：
+
+- 其他非审批相关 experimental 规则形式
+- 无法稳定映射到 command approval 的复杂表达式
+
+对于无法解析的行：
+
+- 忽略该行
+- 写 debug / warn 日志
+- 不让整份 rules 文件失效
+
+### 7.3 命令匹配模型
+
+规则匹配对象是 runtime approval 提供的实际命令。
+
+匹配要求：
+
+1. 先做 shell unwrap，把 `/bin/zsh -lc '...'` 这类外壳剥掉到内部命令串。
+2. 若能安全切分出命令前缀，则按 argv 前缀匹配。
+3. 若历史 rules 本身就是对完整 shell wrapper 的前缀授权，V1 必须优先兼容这类真实历史资产；此时允许对原始命令串做保守前缀匹配，而不是强行 unwrap 后导致历史授权失效。
+4. 若命令包含复杂 shell 运算符、heredoc 或其他不适合前缀拆解的结构，则 V1 只做保守匹配：
+   - 规则命中必须足够明确
+   - 不能因为模糊匹配误放高风险命令
+
+产品原则：
+
+- 宁可复杂命令回落到人工审批，也不能为了“多自动一点”而把不该放的命令误放。
+- 但也不能因为实现只认 unwrap 后的 argv，就把用户已经在官方 Codex 里积累的 shell-wrapper 前缀授权整批作废。
+
+### 7.4 低风险验证 lane 扩展
+
+在现有 `local_self_validation` 基础上扩展支持至少以下类别：
+
+- `cmake -S ... -B ...`
+- `cmake --build ...`
+- `ctest ...`
+- `pytest ...`
+- `cargo test ...`
+- `cargo check ...`
+- `flutter analyze`
+- `dart test`
+- 其他已经在仓库维护流程里稳定出现、且明确属于本地只读/本地验证的命令
+
+约束：
+
+1. `cwd` 必须位于当前项目根或 assistant desk 根内。
+2. 命令不得命中高风险黑名单。
+3. 对 shell 复合命令，只有当每个 segment 都属于低风险验证命令时才自动放行。
+
+### 7.5 决策优先级
+
+命令审批到达后的判断顺序固定为：
+
+1. 高风险黑名单校验
+2. 本地低风险验证 lane
+3. rules 匹配
+4. 默认人工审批
+
+其中：
+
+- 高风险黑名单始终优先于 allow rule
+- assistant 本地 rules 优先于全局 rules
+- `forbidden` 优先于 `prompt`
+- `allow` 只在没有更高优先级阻断时生效
+
+### 7.6 记录与可观测性
+
+新增或补齐以下审计信息：
+
+- `approval_auto_resolved` 带 `policy = local_self_validation | rules_allow`
+- `approval_auto_declined` 带 `policy = rules_forbidden`
+- 规则命中时记录 `matched_rule` 与 `rule_source = assistant | global`
+- 规则解析失败时写 warn 日志，但不打断正常运行
+- `/status` 或排障输出里至少应能说明当前规则是否来自 global / assistant-local 两层，以避免用户误以为 work-ally 只看本地快照
+
+### 7.7 与现有 config 的关系
+
+当前的 `WORK_ALLY_MCP_TOOL_APPROVAL_ALLOWLIST` 继续只服务 MCP tool approval。
+
+本次新增的是 command approval 的 `.rules` 读取与匹配，不把两者混成一个统一 env 变量。
+
+### 7.8 V1 实现护栏
+
+这条专题很容易在“用户确实很痛”这个前提下，顺手把中间层做厚。为了守住 `work-ally` 的产品边界，V1 必须遵守以下护栏：
+
+1. **V1 只做 rules 的读取、继承、匹配与自动处理，不做 rules 写入能力。**
+   - 不新增 Feishu 前台“记住这次”入口。
+   - 不顺手补内部写入接口、双向同步逻辑或规则编辑器。
+2. **V1 只兼容官方 `prefix_rule` 的最小稳定子集。**
+   - 只支持 `allow / prompt / forbidden`。
+   - 不扩展自定义 DSL，不发明第二套规则语法。
+3. **V1 只要求启动加载，不要求运行中热更新。**
+   - 可以缓存。
+   - assistant 重启后必须看到最新 global rules。
+   - 不要求文件监听、增量同步、冲突合并。
+4. **本地低风险验证 lane 只收典型、通用、长期稳定的本地验证命令。**
+   - 不把 repo-specific 命令不断塞进 core 白名单。
+   - 若某项目需要额外放行，应优先通过继承的 global rules 或后续的 assistant-local rules 承接，而不是继续加厚 bridge 核心。
+5. **遇到无法安全判断的命令，宁可回落人工审批，也不靠更多中间层聪明度硬吃。**
+
+一句话护栏：
+
+> 这次 feature 的目标是让 `work-ally` 更好地复用官方已有授权事实，并补一条最小本地验证自治 lane；不是把 bridge 发展成一套新的权限平台。
+
+## 8. 验收标准
+
+满足以下条件才算完成：
+
+1. assistant 在当前项目根 / assistant desk 根内运行典型 build/test/lint/diagnostics 命令时，不再向用户反复发审批卡。
+2. `cmake` / `ctest` 至少被纳入默认低风险验证 lane，并有自动化测试覆盖。
+3. bridge 能成功读取全局 `~/.codex/rules/*.rules` 与 assistant 本地 `rules/*.rules`。
+4. assistant 创建后，如果全局 rules 后续发生变化，assistant 重启后仍能继承最新变化，而不是停留在创建时快照。
+5. 命中 `allow` 规则的命令审批会被自动放行，不向用户发卡。
+6. 命中 `forbidden` 规则的命令审批会被自动拒绝，不向用户发卡。
+7. assistant 本地 rules 与全局 rules 冲突时，本地优先。
+8. 规则解析失败不会导致 bridge 崩溃，也不会让所有审批失效。
+9. archive / timeline 中能区分：本地安全默认自动放行、rules 自动放行、rules 自动拒绝、人工审批。
+10. README / quickstart / troubleshooting 同步更新，明确解释规则来源、持续继承语义、默认优先级与本地验证 lane。
+11. V1 不提供 Feishu 前台“记住这次”写入入口，但文档需明确这是后续能力，而不是遗漏。
+
+## 9. 验证建议
+
+至少补以下验证：
+
+- unit：`.rules` 文件解析与无效行容错
+- unit：命令前缀匹配优先级（assistant local > global）
+- unit：`allow / forbidden / prompt` 三种命中结果
+- unit：`cmake` / `ctest` / `pytest` 等命令被识别为低风险本地验证
+- integration：命中 local_self_validation 时不发审批卡
+- integration：命中 assistant-local rule allow 时不发审批卡
+- integration：命中 global rule allow 且本地无覆盖时不发审批卡
+- integration：命中 local forbidden 覆盖 global allow 时自动拒绝
+- integration：未命中规则且不在自治 lane 时仍发人工审批卡
+- integration：assistant 创建后新增一条 global rule，重启后仍能生效，证明不是 copy-on-create
+- integration：重启后仍可继续读取相同 rules 生效
+- integration：历史 global rule 若以完整 shell wrapper 为前缀，V1 仍能命中并延续既有授权
+
+## 10. 风险 / 假设 / 待决问题
+
+### 10.1 风险
+
+- 如果对复杂 shell 命令的前缀解析过于激进，可能误放高风险命令。
+- 如果低风险验证 lane 过宽，可能把带副作用的本地命令错归到自治路径。
+- 如果文档不讲清楚“默认写 assistant-local rules”，用户可能误以为所有 remembered approvals 都是全局共享。
+- 如果实现偷懒做成 assistant 创建时复制全局 rules，用户在官方 Codex 与 work-ally 间切换时会立即感受到授权历史割裂。
+- 如果 V1 对历史 shell-wrapper 规则兼容不够，文档虽然声称“持续继承 global rules”，实际仍会丢掉一部分最有价值的历史授权资产。
+
+### 10.2 假设
+
+- 官方 `.rules` 的 `prefix_rule` 语法在短期内足够稳定，至少可作为 `work-ally` 的兼容基础。
+- 对 `work-ally` 的长期协作模型来说，assistant-local 规则比全局规则更符合产品语义。
+- 用户对“同一个项目在官方 Codex 里已经放行过的前缀，在 work-ally 里也应继续有效”有强一致预期。
+
+### 10.3 待决问题
+
+1. 是否需要单独增加一条命令查看当前生效 rules 来源与命中结果，方便排障。
+2. 除 `cmake/ctest/pytest/cargo/flutter` 外，是否需要同步纳入更多团队常用本地验证命令。
+3. 后续若增加 Feishu 前台“记住这次”入口，是否还要支持写入全局 rules 的显式高级选项。

package/docs/planning/SPEC-assistant-persona-bootstrap.md

@@ -0,0 +1,199 @@
+# Assistant Persona Bootstrap
+
+更新时间：2026-03-21
+状态：Superseded by `SPEC-remove-cli-persona-bootstrap.md`
+
+## 0. 状态说明
+
+本 spec 已被新的“删除 CLI persona bootstrap”方案取代。当前不应再按本文件继续实现 persona 参数能力；后续请改看 `docs/completed/SPEC-remove-cli-persona-bootstrap.md`。
+
+## 1. 背景
+
+当前 `ally setup <name>` 已经能把 assistant desk、最小配置和默认 `SOUL.md` 一次性创建出来。
+
+但在真实使用里还有一个明显摩擦点：
+
+> 用户刚创建完 assistant，往往立刻就想把“这个人是谁、说话什么风格、做事像谁”一起定义掉。
+
+现在的路径要求用户：
+
+1. 先完成 `ally setup`
+2. 再理解 assistant desk 的存在
+3. 再手动打开 `SOUL.md`
+4. 再自己编辑人格内容
+
+这条路径对维护者是合理的，对普通使用者和新来的协作者并不自然。
+
+## 2. 问题定义
+
+当前缺口不是“没有 `SOUL.md`”，而是**缺少一个面向用户的人设输入层**。
+
+具体问题有三点：
+
+### 2.1 用户意图发生得比 desk 概念更早
+
+用户一上来最关心的是：
+
+- 他叫什么
+- 他是什么角色
+- 他说话是什么感觉
+- 有没有一句稳定签名
+
+而不是：
+
+- `SOUL.md` 在哪个目录
+- 是否需要打开 hidden desk 改 Markdown
+
+### 2.2 当前产品把人格编辑暴露成了文件操作
+
+虽然底层资产用文件表达是对的，但这不应该变成普通用户的第一交互负担。
+
+对用户来说，应该是：
+
+- 我提供一段 persona
+- 产品替我落进正确的长期资产
+
+而不是：
+
+- 我自己去理解并编辑某个内部文件
+
+### 2.3 不能为了“结构化”把简单问题复杂化
+
+用户描述 persona 时，往往天然就是自然语言：
+
+- 男性、架构师、冷静、一针见血
+- 名字叫 Ramond
+- 个性签名是某一句话
+
+如果产品一开始要求用户理解复杂 schema，例如 `role`、`tone`、`signature`、`gender` 之类的独立字段，成本反而更高。
+
+## 3. 目标
+
+在 assistant 创建阶段提供一个**自然语言 persona 输入能力**，让用户可以在 `ally setup` 时一次性把 assistant 的基础人设写进去。
+
+目标是：
+
+1. 普通用户无需先理解 hidden desk
+2. 用户无需直接编辑 `SOUL.md` 才能定义 assistant 人设
+3. 最终人格资产仍然沉淀到标准 `SOUL.md`
+4. 命令语义保持简单，不引入重型 schema
+
+## 4. 非目标
+
+本次不做：
+
+- 自动 AI 生成人设
+- 多套 persona 模板市场
+- 细粒度 schema 化字段设计（如单独 `--role`、`--tone`、`--signature`）
+- 独立 persona 管理面板
+- 已创建 assistant 的交互式 persona 编辑器
+
+## 5. 用户场景
+
+### 场景 A：创建时直接给一句人设
+
+用户希望这样做：
+
+```bash
+ally setup ramond --persona "男性、架构师、专业、冷静、一针见血。个性签名：系统千变万化，底层逻辑如一。专注构建优雅的跨平台基石。"
+```
+
+系统应完成：
+
+- 创建 assistant desk
+- 生成标准 `SOUL.md`
+- 将这段 persona 注入 `SOUL.md` 的用户补充区域
+
+### 场景 B：人设内容较长，希望从文件导入
+
+用户可以这样做：
+
+```bash
+ally setup ramond --persona-file ./ramond-persona.txt
+```
+
+系统应读取文本文件，并按与 `--persona` 相同的方式写入 `SOUL.md`。
+
+## 6. 产品定义
+
+### 6.1 对外命令语义
+
+新增两个参数：
+
+- `--persona <text>`
+- `--persona-file <path>`
+
+支持位置：
+
+- `ally setup <name>`
+- `ally assistant add <name>`
+- `ally assistant ensure <name>`
+
+### 6.2 参数规则
+
+- `--persona` 与 `--persona-file` 二选一，不允许同时传
+- `--persona-file` 必须指向本地可读文本文件
+- 传入空白内容视为无效输入，应直接报错
+
+### 6.3 对内资产规则
+
+对外暴露的是 persona，项目内部真实资产仍是 `SOUL.md`。
+
+也就是说：
+
+- 不新增新的 persona 存储文件
+- 不绕开 `SOUL.md`
+- 不把 persona 只写进 registry description
+
+### 6.4 `SOUL.md` 写入策略
+
+默认模板继续保留。
+
+persona 写入方式：
+
+- 注入到 `SOUL.md` 里清晰的“用户补充设定”区域
+- 不覆盖默认模板中的基础产品纪律
+- 若该区域已存在且当前命令显式传入了 persona，则以新 persona 覆盖旧 persona 区域
+
+这意味着：
+
+- `ally setup ramond --persona ...` 可以一次成型
+- `ally assistant ensure ramond --persona ...` 可以更新 persona
+
+## 7. 核心产品判断
+
+### 7.1 用户输入的是“人设”，不是“文件”
+
+`SOUL.md` 是正确的长期资产，但它属于实现和资产层，不应该成为普通用户的首要概念。
+
+### 7.2 先接受自然语言，再由中间层结构化
+
+V1 应优先接受自然语言 persona，而不是要求用户学习结构化参数。
+
+### 7.3 中间层要吃掉复杂性，但不替用户发明人格
+
+产品负责把 persona 落到正确资产中；不负责擅自扩写、润色或改写用户输入的人设核心语义。
+
+## 8. 验收标准
+
+1. `ally setup <name> --persona "..."` 能成功创建 assistant，并把 persona 写入 `SOUL.md`
+2. `ally setup <name> --persona-file <path>` 能成功读取文件并写入 `SOUL.md`
+3. `--persona` 与 `--persona-file` 同时传入时明确报错
+4. 空 persona 或空文件内容时明确报错
+5. 默认模板中的基础人格纪律仍保留，不会被 persona 覆盖掉整份 `SOUL.md`
+6. `ally assistant ensure <name> --persona "..."` 能更新已有 assistant 的 persona 区域
+7. `docs/user-quickstart.md` 能直接指导用户完成“带 persona 招人”
+
+## 9. 建议实现点
+
+1. 在 shell 入口为 `setup` 与 `assistant add|ensure` 增加 persona 参数解析
+2. 在 assistant bootstrap 层增加 persona 文本归一化与注入逻辑
+3. 为 `SOUL.md` 模板增加稳定的“用户补充设定”区域标记
+4. 补 shell 回归测试覆盖 setup / ensure / persona-file 场景
+5. 同步更新 quickstart、README、manual acceptance、troubleshooting
+
+## 10. 风险与边界
+
+- 若 persona 中包含复杂 Markdown，V1 不保证做富格式保真，只保证文本稳定落库
+- 若 persona-file 不是文本文件，V1 直接按读取失败处理，不做编码探测增强
+- 若用户后续手工编辑 `SOUL.md`，产品不阻止；但再次显式传 persona 时，会只覆盖 persona 区域，不重写整份文件