@awiki/cli 0.0.1-beta.2

package/docs/plan/phase-0/adr-index.md

@@ -0,0 +1,56 @@
+# Phase 0 ADR Index
+
+**状态**：Index frozen, ADR bodies pending as needed  
+**用途**：记录 Phase 0 已识别的强约束决策，供后续阶段引用。  
+**最后更新**：2026-04-04
+
+---
+
+## 1. 使用方式
+
+- 本文件先冻结 ADR 编号、主题和已决定的方向。
+- 若后续需要单独 ADR 文件，可按编号扩展到 `docs/plan/phase-0/adrs/ADR-xxxx-*.md`。
+- 在独立 ADR 文件补齐之前，`implementation-constraints.md` 和 `audit-findings.md` 中的冻结结论视为有效决策正文。
+
+---
+
+## 2. ADR 列表
+
+| ADR | 主题 | 状态 | 影响阶段 | 冻结结论 |
+|---|---|---|---|---|
+| ADR-0001 | 公共命令面冻结 | Frozen | Phase 1+ | 顶级命令以 `status/docs/schema/doctor/version/completion/config/id/msg/group/runtime/people/page/debug` 为准 |
+| ADR-0002 | `group` 域归属 | Frozen | Phase 1+ | `group` 为 canonical 顶级域；`msg send --group` 负责群发消息；`msg group` 只可作为兼容 alias |
+| ADR-0003 | raw API 暴露方式 | Frozen | Phase 1+ | 首发不暴露顶级 `api`；raw RPC 挂在 `debug raw rpc` |
+| ADR-0004 | 用户术语与存储术语 | Frozen | Phase 1+ | 用户层使用 `identity`；存储层 Phase 1 保留 `credential_name` / `default_credential_name` |
+| ADR-0005 | 输出协议与 `_notice` 字段 | Frozen | Phase 1+ | 统一 JSON envelope；更新提示字段固定为 `_notice` |
+| ADR-0006 | 环境变量与路径兼容 | Frozen | Phase 1+ | `AWIKI_*` 为 canonical；`AVIKI_*` / `E2E_*` 作为 legacy 仅供历史参考；v2 原生路径改为单一 `AWIKI_HOME` 工作目录（见实现文档），旧 XDG 路径与 `.openclaw` 仅用于导入检测 |
+| ADR-0007 | 凭证文件基线 | Frozen | Phase 2+ | 凭证布局以 `credential_layout.py` / `credential_store.py` 为基线，兼容 indexed multi-credential layout |
+| ADR-0008 | SQLite 基线与 source of truth | Frozen | Phase 3+ | SQLite 以 `local_store.py` 为 source of truth；`e2ee_outbox` 是首版必保留表 |
+| ADR-0009 | runtime mode 与 listener 边界 | Frozen | Phase 1 / 6+ | transport 只在 `runtime` 暴露；websocket mode 下 listener 持有唯一远端连接 |
+| ADR-0010 | secure 首发范围 | Frozen | Phase 5+ | 首发只做 direct E2EE；group E2EE 不阻塞首发 |
+| ADR-0011 | Go 兼容性与构建策略 | Frozen | Phase 1+ | Go 核心固定使用 Go 1.22，必须 pure Go，无 CGO；系统兼容性壳层可放在 TS shell |
+
+---
+
+## 3. 后续建议的独立 ADR 正文优先级
+
+如果后续要把 ADR 写成独立文件，建议按以下顺序补齐：
+
+1. `ADR-0001` 公共命令面冻结
+2. `ADR-0006` 环境变量与路径兼容
+3. `ADR-0008` SQLite 基线与 source of truth
+4. `ADR-0011` Go 兼容性与构建策略
+5. `ADR-0010` secure 首发范围
+6. `ADR-0009` runtime mode 与 listener 边界
+
+---
+
+## 4. 引用约定
+
+后续文档或代码实现说明里，建议直接引用如下格式：
+
+- `ADR-0001`：公共命令面冻结
+- `ADR-0006`：环境变量与路径兼容
+- `ADR-0011`：Go 兼容性与构建策略
+
+这样可以避免在每个阶段重复解释同一个决定。

package/docs/plan/phase-0/audit-findings.md

@@ -0,0 +1,251 @@
+# Phase 0 审计结论
+
+**状态**：Resolved / Frozen  
+**用途**：记录 Phase 0 审计发现、裁决结果和后续同步动作。  
+**最后更新**：2026-04-04
+
+---
+
+## 1. 审计摘要
+
+本次审计重点比对了四类来源：
+
+1. `docs/architecture/awiki-command-v2.md`
+2. `docs/architecture/awiki-v2-architecture.md`
+3. `../awiki-agent-id-message/`
+4. `../user-service/docs/api/` 与 `../message-service/docs/api/`
+
+审计结论：
+
+- 大方向一致，主要冲突集中在 **命令归属、环境变量命名、raw API 暴露方式、v1 数据基线表述不完整**。
+- 这些冲突都不会阻塞 Phase 1，只要先冻结裁决。
+- 已冻结项必须以后续实现文档和代码为准，原始草案需要后补同步。
+
+---
+
+## 2. 审计发现与裁决
+
+### AF-001：`group` 顶级命令 vs `msg group` 子命令冲突
+
+**证据**：
+
+- `docs/architecture/awiki-v2-architecture.md` 附录 B 使用顶级 `awiki-cli group`
+- `docs/plan/awiki-v2-implementation-plan.md` 也使用顶级 `group`
+- `docs/architecture/awiki-command-v2.md` 的 canonical tree 使用 `awiki-cli msg group ...`
+
+**裁决**：
+
+- canonical 公共命令面采用 **顶级 `group`**
+- `msg group ...` 不作为 Phase 1 必做公共 surface
+- 如果后续实现 `msg group ...`，只能作为兼容 alias
+
+**原因**：
+
+- `group` 是独立领域对象，不只是消息目标
+- 与 `user-service/docs/api/group.md` 更一致
+- 与主实施计划和总体架构更一致
+
+**后续动作**：
+
+- 同步 `awiki-command-v2.md` 的命令树描述
+
+### AF-002：顶级 `api` vs `debug raw rpc` 冲突
+
+**证据**：
+
+- `docs/architecture/awiki-v2-architecture.md` 附录 B 包含顶级 `awiki-cli api`
+- `docs/architecture/awiki-command-v2.md` 只保留 `debug raw rpc`
+
+**裁决**：
+
+- Phase 1 不暴露顶级 `api`
+- raw RPC 统一放在 `debug raw rpc`
+- 顶级 `api` 仅作为未来保留选项，不进入首发契约
+
+**原因**：
+
+- 避免过早暴露额外公共 surface
+- 减少和业务命令层的竞争
+
+**后续动作**：
+
+- 在总体架构附录中把 `api` 标注为 reserve / non-phase-1
+
+### AF-003：环境变量前缀 `AVIKI_*` vs `AWIKI_*` vs `E2E_*`
+
+**证据**：
+
+- `docs/architecture/awiki-command-v2.md` 使用 `AVIKI_*`
+- `../awiki-agent-id-message/` 现有实现、README、测试广泛使用 `AWIKI_*`
+- 旧兼容环境中仍存在 `E2E_*`
+
+**裁决**：
+
+- canonical 前缀冻结为 **`AWIKI_*`**；
+- `AVIKI_*` 与 `E2E_*` 统一视为 legacy / 历史兼容前缀，不再作为 v2 CLI 的正式环境变量集合；
+- v2 实现只暴露少量 `AWIKI_*`（`AWIKI_HOME` / `AWIKI_IDENTITY` / `AWIKI_RUNTIME_MODE` / `AWIKI_FORMAT` / `AWIKI_NO_COLOR`），其余长期配置统一通过 `config.json` 管理。
+
+**原因**：
+
+- `AWIKI_*` 与产品命名一致；
+- 在保留 v1 历史行为可读性的前提下，尽量收敛 v2 的公开环境变量面，减少用户心智负担；
+- 强制把后端域名等长期配置迁移到 `config.json`，避免继续依赖大量 env 组合。
+
+**后续动作**：
+
+- 同步命令文档与主计划文档的相关章节，并在配置/工作目录改造文档中明确新的环境变量收敛方案。
+
+### AF-004：用户层术语 `identity` 与存储层术语 `credential` 不一致
+
+**证据**：
+
+- v2 文档主张使用 `identity`
+- v1 credential layout 与 SQLite 字段中仍使用 `credential_name`、`default_credential_name`
+
+**裁决**：
+
+- 用户层统一使用 `identity`
+- 存储层 Phase 1 保留 `credential_name` / `default_credential_name`，以兼容导入与最小迁移
+- CLI `--identity` 为 canonical 选项
+- `--credential` 如果提供，只能作为 deprecated alias
+
+**原因**：
+
+- 避免对 v1 现有数据和导入器造成不必要破坏
+- 用户层与存储层可以阶段性脱钩
+
+**后续动作**：
+
+- 在 Go 类型层显式建立 identity/credential 桥接
+
+### AF-005：SQLite schema 文档缺失 `e2ee_outbox`
+
+**证据**：
+
+- `../awiki-agent-id-message/references/local-store-schema.md` 未列出 `e2ee_outbox`
+- `../awiki-agent-id-message/scripts/local_store.py` 中明确创建并使用 `e2ee_outbox`
+- `../awiki-agent-id-message/scripts/e2ee_outbox.py` 的 secure resend/drop 完全依赖该表
+
+**裁决**：
+
+- v2 SQLite 基线以 `local_store.py` 为 source of truth
+- `e2ee_outbox` 是首版必保留表，不得省略
+
+**原因**：
+
+- 否则 secure retry / drop / failure recovery 无法保留
+
+**后续动作**：
+
+- 后补同步 `local-store-schema.md`
+
+### AF-006：工作目录方案 vs `.openclaw` 旧路径冲突
+
+**证据**：
+
+- 早期 v2 文档曾按 XDG 路径设计；
+- v1 Python CLI 实际使用 `~/.openclaw/credentials/awiki-agent-id-message/` 与 `~/.openclaw/workspace/data/awiki-agent-id-message/`；
+- Phase 0 之后的配置/工作目录改造文档已经将 v2 原生路径收敛为单一 `AWIKI_HOME` 工作目录。
+
+**裁决**：
+
+- v2 原生写入改为单一工作目录 `AWIKI_HOME`（见 implementation-constraints 5.1），根目录解析规则为：`AWIKI_HOME` 环境变量优先，其次使用默认根（`$HOME/.awiki-cli` / `%LOCALAPPDATA%\AwikiCli`），不再通过 `home.json` 指针跳转；  
+- `doctor` / `runtime setup` / `migrate from-v1` 负责检测 `.openclaw` 旧路径；
+- 默认只提示导入，不原地修改旧数据。
+
+**原因**：
+
+- 统一工作目录比分散的多根 XDG 路径更易于理解、备份和迁移；
+- 清晰区分 v2 新布局与 v1 遗留目录，降低误改旧环境的风险。
+
+**后续动作**：
+
+- 在 migration 和 doctor 中提供显式旧路径检测结果，并确保实现使用 `AWIKI_HOME` 作为唯一新写入根目录。
+
+### AF-007：Go 兼容性策略新增要求——禁止 CGO
+
+**证据**：
+
+- 用户新增要求：Go 核心实现必须 pure Go，保证兼容性，不能使用 CGO
+- 总体架构技术选型中已有“无 CGO SQLite”的方向，但未升级为硬约束
+
+**裁决**：
+
+- `awiki-cli` 主二进制必须保持 **pure Go / no CGO**
+- Phase 1 及之后所有依赖选型都必须默认满足 `CGO_ENABLED=0`
+- 如果需要做系统兼容性、平台安装器或壳层集成，可以放到 **TS shell** 完成，而不是引入 CGO
+
+**原因**：
+
+- 降低多平台发布复杂度
+- 保持二进制可移植性和构建稳定性
+- 避免后续被系统原生依赖锁死
+
+**后续动作**：
+
+- 在技术选型与发布阶段明确验证 `CGO_ENABLED=0`
+
+### AF-008：secure 协议和首发范围仍需冻结
+
+**证据**：
+
+- 总体架构文档明确记录了 E2EE 协议历史冲突
+- v1 secure 流程复杂，涉及 session、outbox、listener auto-processing
+
+**裁决**：
+
+- Phase 0 只冻结首发范围：**direct E2EE 必做，group E2EE 不阻塞首发**
+- 协议具体版本必须由独立 ADR 冻结后再编码
+
+**原因**：
+
+- direct secure 是差异化核心能力
+- group secure 不应阻塞 CLI 壳与 plain path
+
+**后续动作**：
+
+- 进入 Phase 5 前先写完 E2EE 协议 ADR
+
+### AF-009：更新提示字段 `notice` vs `_notice` 冲突
+
+**证据**：
+
+- `docs/architecture/awiki-command-v2.md` 提到冲突收敛
+- `docs/architecture/output-format.md` 使用 `_notice`
+- 飞书 CLI 的输出装饰也倾向于单独 notice 注入字段
+
+**裁决**：
+
+- v2 canonical 输出字段固定为 `_notice`
+- `notice` 不进入新 envelope
+
+**原因**：
+
+- 避免与业务 `data` 混淆
+- 保持统一与稳定
+
+**后续动作**：
+
+- Phase 1 输出层只实现 `_notice`
+
+### AF-010：`discovery` 是否进入 Phase 1 顶级壳
+
+**证据**：
+
+- `awiki-command-v2.md` 的 canonical tree 含 `discovery`
+- 主实施计划的 Phase 1 命令壳列表未把 `discovery` 设为必须
+
+**裁决**：
+
+- `discovery` 视为保留扩展域
+- Phase 1 可以不实现顶级 `discovery` 壳
+- 真正进入实现时不晚于 Phase 7/扩展域
+
+**原因**：
+
+- 避免在核心壳阶段引入未稳定工作流
+- 不影响 `id/msg/group/runtime` 主链路
+
+**后续动作**：
+
+- 在 docs/help 中将 `discovery` 标注为 reserved extension

package/docs/plan/phase-0/capability-mapping.md

@@ -0,0 +1,108 @@
+# Phase 0 能力映射表
+
+**状态**：Frozen mapping baseline  
+**用途**：为 Phase 1~Phase 5 提供命令迁移、API 对接、测试覆盖范围的基准表。  
+**最后更新**：2026-04-04
+
+---
+
+## 1. 映射原则
+
+- 优先以 **能力** 建模，而不是按文件名建模。
+- v2 的 canonical surface 以 `awiki-cli` 命令为准。
+- v1 Python 仓库只作为实现和迁移参考，不要求保持脚本级一一映射。
+- 如果一个 v2 命令对应多个 v1 脚本或多个 API 方法，映射表必须显式列出，而不是省略。
+
+---
+
+## 2. v2 命令 ↔ v1 脚本映射
+
+| v2 命令 / 域 | v1 参考脚本 | 说明 |
+|---|---|---|
+| `status` | `scripts/check_status.py` | 统一状态检查的主要参考 |
+| `docs` | 无 | v2 新增产品能力 |
+| `schema` | 无 | v2 新增机器契约能力 |
+| `doctor` | `scripts/check_status.py` + `scripts/database_migration.py` + `scripts/migrate_credentials.py` + `scripts/migrate_local_database.py` | v2 需要把分散诊断入口收敛 |
+| `version` | 无 | v2 新增标准 CLI 能力 |
+| `completion` | 无 | v2 新增标准 CLI 能力 |
+| `config` | `scripts/utils/config.py`（实现参考） | v1 无独立公共命令 |
+| `id status/create/list/current/use` | `scripts/setup_identity.py` | v1 的 DID identity 入口 |
+| `id register` | `scripts/send_verification_code.py` + `scripts/register_handle.py` | v2 收敛成一次身份注册流 |
+| `id bind` | `scripts/bind_contact.py` | 手机 / 邮箱绑定 |
+| `id resolve` | `scripts/resolve_handle.py` + `scripts/get_profile.py --resolve` | DID / Handle / DID document 解析 |
+| `id recover` | `scripts/recover_handle.py` | Handle 恢复 |
+| `id profile get` | `scripts/get_profile.py` | 读自己或公开资料 |
+| `id profile set` | `scripts/update_profile.py` | 更新 DID Profile |
+| `msg send --to ... --secure off` | `scripts/send_message.py` | 私聊明文消息 |
+| `msg inbox` / `msg history` / `msg mark-read` | `scripts/check_inbox.py` | 收件箱、历史、已读管理 |
+| `msg send --group ...` | `scripts/manage_group.py --post-message` | 群发消息 |
+| `group create/show/update/join/leave/kick/members/messages/code*` | `scripts/manage_group.py` | 群生命周期与本地快照 |
+| `msg secure status/init/repair/failed/retry/drop` | `scripts/e2ee_messaging.py` | secure 命令面从 v1 E2EE 脚本收敛 |
+| `runtime setup` / `runtime mode *` | `scripts/setup_realtime.py` + `scripts/message_transport.py` | 运行模式编排与持久化 |
+| `runtime listener *` | `scripts/ws_listener.py` + `scripts/service_manager.py` | listener 生命周期 |
+| `runtime heartbeat *` | `scripts/setup_realtime.py` + `references/HEARTBEAT.md` | v1 无完整独立公共命令 |
+| `people search` | `scripts/search_users.py` | 用户搜索 |
+| `people follow/unfollow/status/followers/following` | `scripts/manage_relationship.py` | 关系管理 |
+| `people contacts list/save` | `scripts/manage_contacts.py` | 本地联系人沉淀 |
+| `page create/list/get/update/rename/delete` | `scripts/manage_content.py` | 内容页管理 |
+| `debug db query` | `scripts/query_db.py` | 本地 SQLite 调试 |
+| `debug raw rpc` | 无统一单脚本；参考 `scripts/utils/rpc.py`、各域脚本 RPC 调用 | v2 新收敛入口 |
+| `discovery *` | 无单一脚本；组合 `manage_group.py` + `manage_contacts.py` + `relationship_events` + `references/GROUP_DISCOVERY_GUIDE.md` | v2 明确化工作流，v1 主要靠组合流程 |
+
+---
+
+## 3. v2 命令 ↔ user-service API 映射
+
+| v2 命令 | API 文档 | 关键方法 / 范围 |
+|---|---|---|
+| `id register` | `user-service/docs/api/authentication.md` + `handle.md` | 发送验证码、邮箱验证、handle 注册、quota 检查 |
+| `id bind` | `user-service/docs/api/authentication.md` | 手机号绑定、邮箱绑定 |
+| `id resolve` | `user-service/docs/api/handle.md` + `did-profile.md` | handle lookup / DID resolve |
+| `id profile get/set` | `user-service/docs/api/profile.md` + `did-profile.md` | `get_me` / `update_me` / public profile |
+| `people follow/unfollow/status/followers/following` | `user-service/docs/api/relationships.md` | `follow` / `unfollow` / `get_status` / `get_followers` / `get_following` |
+| `group create/show/update/join/leave/kick/members/code*` | `user-service/docs/api/group.md` | `create` / `get` / `update` / `refresh_join_code` / `get_join_code` / `set_join_enabled` / `join` / `leave` / `kick_member` / `list_members` |
+| `page *` | `user-service/docs/api/content.md` | 内容页创建、更新、删除、查询 |
+| `credits *`（若未来恢复） | `user-service/docs/api/credits.md` | 信用余额与规则，当前不在 canonical 首发面 |
+
+---
+
+## 4. v2 命令 ↔ message-service API 映射
+
+| v2 命令 | API 文档 | 关键方法 / 范围 |
+|---|---|---|
+| `msg send --to` | `message-service/docs/api/ANP-client-server-api-direct.md` | `direct.send` |
+| `msg inbox` | `ANP-client-server-api-direct.md` | `inbox.get` |
+| `msg mark-read` | `ANP-client-server-api-direct.md` | `inbox.mark_read` |
+| `msg history --with` | `ANP-client-server-api-direct.md` | `direct.get_history` |
+| `msg secure *` | `ANP-client-server-api-direct.md` | prekey bundle、E2EE init/ack/msg、local view 兼容 |
+| `msg send --group` | `message-service/docs/api/ANP-client-server-api-group.md` | `group.send` |
+| `group messages` | `ANP-client-server-api-group.md` | `group.list_messages` |
+| group realtime / state changes | `ANP-client-server-api-group.md` | `group.incoming` / `group.state_changed` WS 通知 |
+| 附件增强能力 | `ANP-client-server-api-attachment.md` | `attachment.create_slot` / `commit_object` / `get_download_ticket` |
+
+---
+
+## 5. 新能力与非一对一收敛项
+
+下列能力在 v2 中是新增或重组后的产品能力，不要求在 v1 中找到单一脚本：
+
+| v2 能力 | 来源 | 说明 |
+|---|---|---|
+| `docs` | v2 新能力 | 产品内建文档入口 |
+| `schema` | v2 新能力 | 机器可读命令契约 |
+| `doctor` | v1 多脚本诊断收敛 | 配置/identity/runtime/SQLite 统一诊断 |
+| `completion` | v2 新能力 | shell completion |
+| `debug raw rpc` | v1 各脚本零散 RPC 调用收敛 | 原始 RPC 兜底入口 |
+| `discovery *` | v1 workflow 组合收敛 | 群发现、推荐、草稿生成 |
+
+---
+
+## 6. Phase 1~Phase 5 的实现优先级映射
+
+| 阶段 | 先实现的域 | 主要参考 |
+|---|---|---|
+| Phase 1 | CLI 壳、`status/docs/schema/doctor/version/completion/config` | `../cli/` + v2 架构文档 |
+| Phase 2 | `id` + identity store + credential import | `setup_identity.py` / `register_handle.py` / `bind_contact.py` / `credential_layout.py` |
+| Phase 3 | SQLite schema + migration | `local_store.py` / `database_migration.py` / `local-store-schema.md` |
+| Phase 4 | `msg` + `group` plain path | `send_message.py` / `check_inbox.py` / `manage_group.py` + message/group API docs |
+| Phase 5 | `msg secure *` | `e2ee_messaging.py` / `e2ee_session_store.py` / `e2ee_outbox.py` |