chore(mas): initialize split project metadata

Ariver

2026-07-12 33f00a1136c9f7e501b989d432b709d632905304

chore(mas): initialize split project metadata

 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` 项目复制代码、提交或任务；不在本目录保存凭据。

 C1.source/AGENTS.md

New file
@@ -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 证据的回读。

 C1.source/CODEGRAPH.md

New file
@@ -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`；完成后更新本图与证据路径。

 K1.业务知识/README.md

New file
@@ -0,0 +1,13 @@
# K1.业务知识

本目录保存长期有效的产品、领域和系统行为知识。

适合放入这里的内容：

- PrivateVoice-MAS 长期产品决策。
- 用户任务、领域规则、系统能力和限制。
- 可复用的错误文案、验收口径和领域知识。
- 长期有效的技术约束、状态模型和系统行为知识。
- `成果地图.md` 中索引到的稳定成果和事实源。

不放 Round 过程记录；过程记录留在 `02-P/`。

 K2.项目管理/QA地图.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 台账。

 K2.项目管理/QA成果地图.md

New file
@@ -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 / 主流程 / 数据层 / 发布前检查门禁

 K2.项目管理/README.md

New file
@@ -0,0 +1,14 @@
# K2.项目管理

本目录保存长期有效的项目管理、协作、复盘和交付经验。

适合放入这里的内容：

- PrivateVoice-MAS 项目级 SOP。
- QA 门禁和验证地图。
- 阶段复盘。
- 交付验收经验。
- 新 Agent / 新 session 接手指南。
- 多角色协作规则的项目特例。

不复制全局规则；全局规则只在本项目有特例时才补充说明。

 K2.项目管理/新窗口接手指南.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` 和项目全局规则执行对应门禁；本迁移没有运行构建或发布。

 K2.项目管理/研发交付验收流程.md

New file
@@ -0,0 +1,23 @@
# PrivateVoice-MAS 研发交付验收流程

最后整理：2026-07-11

## 标准链路

```text
目标对齐
  -> 当前 Round 包
  -> 技术方案
  -> 实现
  -> 代码审核
  -> QA
  -> 发布准备
  -> 用户 / Owner 验收
```

## 规则

- 不跳过 `02-P/进度地图.md` 直接派工。
- 不跳过技术方案直接进入非平凡实现。
- 不跳过 QA 直接进入发布准备。
- 交付结论必须落在文档，而不是只留在会话中。

 K2.项目管理/项目经理-经验与教训.md

New file
@@ -0,0 +1,15 @@
# PrivateVoice-MAS 项目经理-经验与教训

最后整理：2026-07-11

## 当前状态

项目尚处初始化阶段，暂无长期有效经验教训。

## 后续记录范围

- 计划失真原因
- 交接失败原因
- 文档入口失效原因
- 规则树冗余或缺口
- 哪些流程在真实执行中有效，哪些只是纸面结构