From 33f00a1136c9f7e501b989d432b709d632905304 Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Sun, 12 Jul 2026 02:09:04 +0800
Subject: [PATCH] chore(mas): initialize split project metadata
---
K2.项目管理/QA成果地图.md | 23 +++
K2.项目管理/QA地图.md | 55 +-------
K1.业务知识/README.md | 13 ++
AGENTS.md | 40 +-----
K2.项目管理/新窗口接手指南.md | 59 ++-------
C1.source/AGENTS.md | 24 ++++
K2.项目管理/项目经理-经验与教训.md | 15 ++
C1.source/CODEGRAPH.md | 37 ++++++
K2.项目管理/研发交付验收流程.md | 23 +++
K2.项目管理/README.md | 14 ++
10 files changed, 183 insertions(+), 120 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 6dc822f..abeea91 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,35 +1,7 @@
-## 项目属性
+# PrivateVoice-MAS 03-O 局部规则
-项目类型：研发项目
-主要产物：Wails v3 / Go 桌面语音输入 App
-
-## 读取顺序
-
-如果当前工作目录在 `03-O` 内，先回到项目根入口读取：
-
-1. `/Users/ar/Projects/PrivateVoice/AGENTS.md`
-2. `/Users/ar/Projects/PrivateVoice/PROJECT.md`
-3. `/Users/ar/Projects/PrivateVoice/INDEX.md`
-4. `/Users/ar/Projects/PrivateVoice/02-P/进度地图.md`
-5. `/Users/ar/Projects/PrivateVoice/03-O/CODEGRAPH.md`
-
-旧 `K2.项目管理/legacy/` 资料只作证据附件，不能作为活跃任务来源。
-
-## 路径边界
-
-- 项目根：`/Users/ar/Projects/PrivateVoice`
-- Git 根：`/Users/ar/Projects/PrivateVoice/03-O`
-- 源码根：`/Users/ar/Projects/PrivateVoice/03-O/C1.source/privatevoice.src`
-- 构建/发布候选包：`/Users/ar/Projects/PrivateVoice/03-O/C2.builds`
-- 构建与 QA 脚本：源码内 `C1.source/privatevoice.src/scripts/`，`C3.tools/` 只放索引和迁移工具说明。
-- 会话记忆目录：`/Users/ar/Projects/PrivateVoice/.codex-sessionhistory/`
-- 常规会话主题汇编目录：`/Users/ar/Projects/PrivateVoice/.codex-sessionhistory/00-Topics.md` 和 `/Users/ar/Projects/PrivateVoice/.codex-sessionhistory/_topics/`。`K2.项目管理/session-topics/` 只保存旧项目迁移压缩摘要，不得作为新项目常规主题汇编落点。
-
-## 工作规则
-
-- 统一活跃台账是 `/Users/ar/Projects/PrivateVoice/02-P/进度地图.md`。
-- `CODEGRAPH.md` 是人工维护工程地图；自动索引或缓存不能替代它。
-- `codebase-memory` 状态为 `enabled`；标准刷新命令是 `codebase-memory-mcp cli index_repository '{"repo_path":"/Users/ar/Projects/PrivateVoice/03-O"}'`，共享产物为 `.codebase-memory/graph.db.zst` 和 `.codebase-memory/artifact.json`。
-- 每次源码冻结、版本冻结、正式可回滚测试包或发布包前必须刷新 `.codebase-memory/`；日常 Coder 中间态变更不强制刷新。
-- 发布、QA、签名、打包和版本冻结必须遵守项目根入口声明的全局规则路由。
-- 标准验证命令必须保持原始可执行形式，不在命令本身追加输出截断管道。
+- 本目录是 `/Users/ar/Projects/PrivateVoice-MAS` 的 Git 根，当前分支为 `mas`。
+- 当前源码根：`C1.source/`；代码地图：`C1.source/CODEGRAPH.md`。
+- 进入源码前先读取项目根 `AGENTS.md`、`PROJECT.md`、`02-P/进度地图.md` 和本目录代码地图。
+- `C2.builds/` 放本地构建和发布候选，`K2.项目管理/` 放证据与门禁，`K3.运营与发布资料/` 放 MAS 渠道资料。
+- 不从 `independent-developer` 项目复制代码、提交或任务；不在本目录保存凭据。
diff --git a/C1.source/AGENTS.md b/C1.source/AGENTS.md
new file mode 100644
index 0000000..897fd13
--- /dev/null
+++ b/C1.source/AGENTS.md
@@ -0,0 +1,24 @@
+# AGENTS.md - PrivateVoice-MAS 源码区规则
+
+本目录是 PrivateVoice-MAS 当前 `mas` 分支的源码根目录。
+
+## 必读
+
+涉及源码、测试、构建、模块边界或非平凡实现时，先读：
+
+1. `/Users/ar/Projects/PrivateVoice-MAS/AGENTS.md`
+2. `/Users/ar/Projects/PrivateVoice-MAS/PROJECT.md`
+3. `/Users/ar/Projects/PrivateVoice-MAS/03-O/README.md`
+4. `/Users/ar/Projects/PrivateVoice-MAS/03-O/C1.source/CODEGRAPH.md`
+5. 当前 Round 的产品定义、技术方案和验收文档
+6. 涉及 UI 时读 `/Users/ar/Projects/PrivateVoice-MAS/DESIGN.md`
+
+## 代码规则
+
+- 只实现当前任务直接需要的代码。
+- 复用系统能力和现有模块，不为一次性需求创建抽象层。
+- 不把输入资料中的功能直接当成已确认需求。
+- Git 命令默认在 `/Users/ar/Projects/PrivateVoice-MAS/03-O` 执行，而不是本目录。
+- 新增或移动源码后，同步更新本目录 `CODEGRAPH.md`。
+- 构建、测试、QA 脚本优先放到 `../C3.tools/`，除非工程工具链要求必须随源码放置。
+- 自动图谱结果只能辅助定位，不能替代对真实源码、测试和 QA 证据的回读。
diff --git a/C1.source/CODEGRAPH.md b/C1.source/CODEGRAPH.md
new file mode 100644
index 0000000..b6bb2fe
--- /dev/null
+++ b/C1.source/CODEGRAPH.md
@@ -0,0 +1,37 @@
+# PrivateVoice-MAS CODEGRAPH
+
+最后整理：2026-07-11
+
+## 工程范围
+
+- 项目根：`/Users/ar/Projects/PrivateVoice-MAS`
+- Git 根：`/Users/ar/Projects/PrivateVoice-MAS/03-O`
+- 分支：`mas`
+- 源码冻结基线：`015f1089ea875a153dd2a18ef42c25145d4868f5`；项目初始化元数据提交见 `git log`。
+- 源码根：`/Users/ar/Projects/PrivateVoice-MAS/03-O/C1.source/privatevoice.src`
+- 当前验证基线：`2.2.3 / build 20260711.1807`
+- 自动图谱：`../.codebase-memory/`；它只辅助定位，不替代本地图。
+
+## 核心入口
+
+| 区域 | 入口 |
+| --- | --- |
+| Wails / 生命周期 | `privatevoice.src/main.go`、`privatevoice.src/app.go` |
+| 语音输出路由 | `privatevoice.src/internal/textoutput/router.go`、`router_appstore_darwin.go` |
+| Accessibility | `privatevoice.src/internal/axinput/axinput_darwin.go` |
+| 剪贴板 fallback | `privatevoice.src/internal/axinput/clipboard_fallback_darwin_test.go`、text output service/router |
+| 设置与 fallback UI | `privatevoice.src/frontend/src/components/settings/GeneralPage.svelte`、`TextOutputFallbackPanel.svelte` |
+| MAS 构建 | `privatevoice.src/scripts/build-macappstore-pkg-macos.sh` |
+
+## 受保护行为
+
+- MAS direct AX 只做 best-effort；不能把 focused-element 失败误报为成功。
+- 可靠输出路径是写入最新文本后自动触发受保护 `Cmd+V`；显式 fallback 仍然需要安全目标判断。
+- Terminal / shell / console / terminal-role 目标不得自动写入、粘贴或执行命令。
+- 日志和 UI 不记录 transcript、target、method、message、窗口标题或文档标题。
+
+## QA / 发布入口
+
+- QA 与发布证据：`../K2.项目管理/`、`../K3.运营与发布资料/` 及根 `02-P/X-Archived/`。
+- 当前项目不从 independent-developer 项目领取源码或任务。
+- 非平凡实现前先读取本文件、项目根入口和 `02-P/进度地图.md`；完成后更新本图与证据路径。
diff --git "a/K1.\344\270\232\345\212\241\347\237\245\350\257\206/README.md" "b/K1.\344\270\232\345\212\241\347\237\245\350\257\206/README.md"
new file mode 100644
index 0000000..5bf7297
--- /dev/null
+++ "b/K1.\344\270\232\345\212\241\347\237\245\350\257\206/README.md"
@@ -0,0 +1,13 @@
+# K1.业务知识
+
+本目录保存长期有效的产品、领域和系统行为知识。
+
+适合放入这里的内容：
+
+- PrivateVoice-MAS 长期产品决策。
+- 用户任务、领域规则、系统能力和限制。
+- 可复用的错误文案、验收口径和领域知识。
+- 长期有效的技术约束、状态模型和系统行为知识。
+- `成果地图.md` 中索引到的稳定成果和事实源。
+
+不放 Round 过程记录；过程记录留在 `02-P/`。
diff --git "a/K2.\351\241\271\347\233\256\347\256\241\347\220\206/QA\345\234\260\345\233\276.md" "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/QA\345\234\260\345\233\276.md"
index f67a5e1..b11a706 100644
--- "a/K2.\351\241\271\347\233\256\347\256\241\347\220\206/QA\345\234\260\345\233\276.md"
+++ "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/QA\345\234\260\345\233\276.md"
@@ -1,48 +1,15 @@
-# QA 地图
+# PrivateVoice-MAS QA 地图
-## 当前 QA 结论
+## 当前边界
-迁移接收验证与产品 QA 结论必须区分。
+- 当前验收基线：TestFlight `2.2.3 / 20260711.1807`。
+- Owner 已验证自动输入、连续轮次最新文本、剪贴板恢复和 Terminal 负向；这些是历史证据，路径见 `02-P/X-Archived/`。
+- direct AX 仍是 best-effort；MAS QA 必须优先验证自动输出安全边界和 fallback，不得把 direct 失败伪装成 PASS。
+- 本迁移没有重新运行构建、测试或真实设备 QA。
-- 迁移接收验证：由 `接收验证记录.md` 记录。
-- Round 6 产品 QA：已有会话和 release manifest 证明基础自动化/包校验通过。
-- Windows 真机 QA：仍未由本迁移补跑。
-- 官网正式发布 QA：仍未完成 notarization、下载页、授权/激活、更新和回滚链路验证。
+## 责任入口
-## 标准源码验证
-
-从 `03-O/C1.source/privatevoice.src` 执行：
-
-```bash
-npm --prefix frontend run build
-go test ./...
-GOOS=windows GOARCH=amd64 CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc CXX=x86_64-w64-mingw32-g++ go test -exec=/usr/bin/true ./...
-```
-
-## 包验证
-
-从 `03-O/C2.builds/PrivateVoice-Dictation-2.2.0-build20260702.0303` 执行：
-
-```bash
-shasum -a 256 -c SHA256SUMS.txt
-hdiutil verify 'PrivateVoice-Dictation-2.2.0-build20260702.0303-macos-arm64.dmg'
-hdiutil verify 'PrivateVoice-Dictation-2.2.0-build20260702.0303-macos-x86_64.dmg'
-hdiutil verify 'PrivateVoice-Dictation-2.2.0-build20260702.0303-macos-universal.dmg'
-unzip -t 'PrivateVoice-Dictation-2.2.0-build20260702.0303-windows-amd64-preview.zip'
-```
-
-## Windows QA 入口
-
-在 Windows preview 包解压后运行：
-
-```text
-RUN-WINDOWS-QA.cmd
-```
-
-收回 evidence zip 后，在源码根执行：
-
-```bash
-./scripts/verify-windows-qa-evidence.sh /path/to/qa-evidence-YYYYMMDD-HHMMSS.zip
-```
-
-只有出现 `WINDOWS_QA_EVIDENCE_PASS`，才能声称 Windows preview evidence 通过。
+- 当前活跃任务：`02-P/进度地图.md`。
+- 代码地图：`03-O/C1.source/CODEGRAPH.md`。
+- 发布资料历史：`02-P/X-Archived/source-K3-docs/`。
+- 任何新 QA 必须形成证据并回报 MAS PMO，不得回写 independent-developer 台账。
diff --git "a/K2.\351\241\271\347\233\256\347\256\241\347\220\206/QA\346\210\220\346\236\234\345\234\260\345\233\276.md" "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/QA\346\210\220\346\236\234\345\234\260\345\233\276.md"
new file mode 100644
index 0000000..2270a7a
--- /dev/null
+++ "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/QA\346\210\220\346\236\234\345\234\260\345\233\276.md"
@@ -0,0 +1,23 @@
+# PrivateVoice-MAS QA 成果地图
+
+最后整理：2026-07-11
+
+## 当前状态
+
+PrivateVoice-MAS 尚未建立真实源码工程，本文件先作为未来 QA 门禁和验证入口的总地图。
+
+## 当前已建立入口
+
+| 类型 | 路径 | 状态 |
+| --- | --- | --- |
+| 当前验收口径 | `02-P/Round00-Foundation/04-QA与验收.md` | 已建立 |
+| 工程地图入口 | `03-O/C1.source/CODEGRAPH.md` | 已建立 |
+| 构建产物根 | `03-O/C2.builds/` | 已建立 |
+| 工具脚本根 | `03-O/C3.tools/` | 已建立 |
+
+## 后续应补
+
+- 真实构建命令
+- 真实测试命令
+- 首个 QA 脚本入口
+- 主 UI / 主流程 / 数据层 / 发布前检查门禁
diff --git "a/K2.\351\241\271\347\233\256\347\256\241\347\220\206/README.md" "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/README.md"
new file mode 100644
index 0000000..5538eaa
--- /dev/null
+++ "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/README.md"
@@ -0,0 +1,14 @@
+# K2.项目管理
+
+本目录保存长期有效的项目管理、协作、复盘和交付经验。
+
+适合放入这里的内容：
+
+- PrivateVoice-MAS 项目级 SOP。
+- QA 门禁和验证地图。
+- 阶段复盘。
+- 交付验收经验。
+- 新 Agent / 新 session 接手指南。
+- 多角色协作规则的项目特例。
+
+不复制全局规则；全局规则只在本项目有特例时才补充说明。
diff --git "a/K2.\351\241\271\347\233\256\347\256\241\347\220\206/\346\226\260\347\252\227\345\217\243\346\216\245\346\211\213\346\214\207\345\215\227.md" "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/\346\226\260\347\252\227\345\217\243\346\216\245\346\211\213\346\214\207\345\215\227.md"
index bf65f20..19cd62d 100644
--- "a/K2.\351\241\271\347\233\256\347\256\241\347\220\206/\346\226\260\347\252\227\345\217\243\346\216\245\346\211\213\346\214\207\345\215\227.md"
+++ "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/\346\226\260\347\252\227\345\217\243\346\216\245\346\211\213\346\214\207\345\215\227.md"
@@ -1,52 +1,27 @@
-# 新窗口接手指南
-
-## 接手目标
-
-从 `/Users/ar/Projects/PrivateVoice` 文件系统接手项目，不依赖旧长会话上下文。`PrivateVoice2` 只是迁移期间旧命名，不再作为当前路径。
+# PrivateVoice-MAS 新窗口接手指南
## 必读顺序
-1. `/Users/ar/Projects/PrivateVoice/AGENTS.md`
-2. `/Users/ar/Projects/PrivateVoice/PROJECT.md`
-3. `/Users/ar/Projects/PrivateVoice/INDEX.md`
-4. `/Users/ar/Projects/PrivateVoice/02-P/进度地图.md`
-5. `/Users/ar/Projects/PrivateVoice/02-P/事件地图.md`
-6. `/Users/ar/Projects/PrivateVoice/03-O/CODEGRAPH.md`
-7. `/Users/ar/Projects/PrivateVoice/03-O/K2.项目管理/迁移资产清单.md`
+1. `/Users/ar/Projects/PrivateVoice-MAS/AGENTS.md`
+2. `/Users/ar/Projects/PrivateVoice-MAS/PROJECT.md`
+3. `/Users/ar/Projects/PrivateVoice-MAS/02-P/进度地图.md`
+4. `/Users/ar/Projects/PrivateVoice-MAS/02-P/事件地图.md`
+5. `/Users/ar/Projects/PrivateVoice-MAS/03-O/C1.source/CODEGRAPH.md`
+6. `/Users/ar/Projects/PrivateVoice-MAS/03-O/K2.项目管理/迁移资产清单.md`
-## 当前事实快照
+## 接手事实
-- 当前工作不是继续旧会话，而是从新项目文件接手。
-- 源码根：`03-O/C1.source/privatevoice.src`
-- 当前基线：`v2.2.0-build20260702.0303-real-user-test`
-- Round 6 粤语实现和四包候选已完成。
-- Windows preview 与官网正式发布仍有缺口。
+- Git 根：`/Users/ar/Projects/PrivateVoice-MAS/03-O`
+- 分支：`mas`
+- 代码基线：`015f1089` / TestFlight `2.2.3 / 20260711.1807`
+- 当前任务只从 `/Users/ar/Projects/PrivateVoice-MAS/02-P/进度地图.md` 领取。
+- independent-developer 是另一项目，不共享工作树、任务或发布结论。
-## 接手自检命令
+## 接手自检
```bash
-cd /Users/ar/Projects/PrivateVoice/03-O
-git status --short --branch
-git diff --check
-cd C1.source/privatevoice.src
-npm --prefix frontend run build
-go test ./...
+git -C /Users/ar/Projects/PrivateVoice-MAS/03-O status --short --branch
+git -C /Users/ar/Projects/PrivateVoice-MAS/03-O diff --check
```
-## 不迁移内容
-
-- 原始长会话正文。
-- 旧 worktree。
-- 旧构建包全集。
-- 证书目录。
-- node_modules、dist、构建缓存和用户级缓存。
-
-## 成功判定
-
-新窗口只读新项目文件后，应能说明：
-
-- 项目是什么。
-- 当前做到哪里。
-- Git 根、源码根、QA 入口和发布入口在哪里。
-- 下一步需要谁决策。
-- 哪些材料是 legacy，不可直接作为当前任务来源。
+涉及源码、构建、QA 或发布时，再按 `CODEGRAPH.md` 和项目全局规则执行对应门禁；本迁移没有运行构建或发布。
diff --git "a/K2.\351\241\271\347\233\256\347\256\241\347\220\206/\347\240\224\345\217\221\344\272\244\344\273\230\351\252\214\346\224\266\346\265\201\347\250\213.md" "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/\347\240\224\345\217\221\344\272\244\344\273\230\351\252\214\346\224\266\346\265\201\347\250\213.md"
new file mode 100644
index 0000000..4164fce
--- /dev/null
+++ "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/\347\240\224\345\217\221\344\272\244\344\273\230\351\252\214\346\224\266\346\265\201\347\250\213.md"
@@ -0,0 +1,23 @@
+# PrivateVoice-MAS 研发交付验收流程
+
+最后整理：2026-07-11
+
+## 标准链路
+
+```text
+目标对齐
+ -> 当前 Round 包
+ -> 技术方案
+ -> 实现
+ -> 代码审核
+ -> QA
+ -> 发布准备
+ -> 用户 / Owner 验收
+```
+
+## 规则
+
+- 不跳过 `02-P/进度地图.md` 直接派工。
+- 不跳过技术方案直接进入非平凡实现。
+- 不跳过 QA 直接进入发布准备。
+- 交付结论必须落在文档，而不是只留在会话中。
diff --git "a/K2.\351\241\271\347\233\256\347\256\241\347\220\206/\351\241\271\347\233\256\347\273\217\347\220\206-\347\273\217\351\252\214\344\270\216\346\225\231\350\256\255.md" "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/\351\241\271\347\233\256\347\273\217\347\220\206-\347\273\217\351\252\214\344\270\216\346\225\231\350\256\255.md"
new file mode 100644
index 0000000..4b99318
--- /dev/null
+++ "b/K2.\351\241\271\347\233\256\347\256\241\347\220\206/\351\241\271\347\233\256\347\273\217\347\220\206-\347\273\217\351\252\214\344\270\216\346\225\231\350\256\255.md"
@@ -0,0 +1,15 @@
+# PrivateVoice-MAS 项目经理-经验与教训
+
+最后整理：2026-07-11
+
+## 当前状态
+
+项目尚处初始化阶段，暂无长期有效经验教训。
+
+## 后续记录范围
+
+- 计划失真原因
+- 交接失败原因
+- 文档入口失效原因
+- 规则树冗余或缺口
+- 哪些流程在真实执行中有效，哪些只是纸面结构
--
Gitblit v1.9.3