a073d95f1c
Some checks failed
SDK CI / python-compile (push) Has been cancelled
保留源码与部署文档，排除超大二进制和本地运行配置。
12 KiB
12 KiB
tags, doc-type, layer, parent, related, name, description, owner, version
| tags | doc-type | layer | parent | related | name | description | owner | version | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
SKILL | 机擎/阿表/开发文档结构规范 |
|
|
workphone-devdoc-structure | 阿表 | 1.2.0 |
工作手机 · 开发文档结构规范（阿表 · 开发时必守）
归属：机擎 / 阿表
范围：开发文档/全部 1～10 目录；本 Skill 与 机擎/阿表/SKILL.md 同时加载
激情原则：文档不是事后补录——每做一个功能，当场归类、当场写进对应目录，保持 Obsidian 里一眼能扫清。
一、总规则（8+2 条）
| # | 规则 |
|---|---|
| 1 | 所有开发文档 只在 开发文档/ 下，禁止散落仓库根 |
| 2 | 每子目录除 README 外 ≤3 个主文档；超出须合并，不得丢内容 |
| 3 | PNG/JPG 一律进该目录的 images/ 子树，禁止 vault 根 Pasted image；引用用 绝对路径 Markdown（见 §四D） |
| 4 | 目录命名：01-大类名/ 数字前缀表示从大到小；images/ 内用 01-子类/ |
| 5 | 每个大类目录必须有 README.md（索引 + Obsidian obsidian-color） |
| 6 | 新功能开发完 → 同步 3 处：功能 MD + 10、项目管理/工作日志.md + 涉及目录 README |
| 7 | 改路径 → 同步 sdk/app/main.py（_DOC_PAGE_MAP、_scan_arch_assets） |
| 8 | 进度真源不变：10、项目管理/开发进度总表.md + 2、架构/01-总览/系统架构.md §3.0 |
| +1 | Obsidian：新目录在 .obsidian/snippets/workphone-devdoc.css 登记配色 |
| +3 | 标签与关联：每篇 MD 必有 YAML tags + related + parent；文末 🔗 关联导航（工作日志/历史追加包除外） |
二、2、架构 标准树（现行真源）
开发文档/2、架构/
├── README.md
├── images/
│ ├── README.md
│ ├── 01-整体总览/ # SDK全景、Agent工作流、设备运转
│ ├── 02-控制通道/ # 五通道 P1～P5
│ ├── 03-微信与Hook/ # 微信链路、Hook交互
│ └── 04-防封/
├── 01-总览/ # 系统架构.md（§3.0 模块拆解）
├── 02-技术基座/ # 技术选型与数据库.md
├── 03-通道与设备/ # Hook通道与多设备多服务器架构.md
├── 04-交互图/ # *.html、*.mmd
└── 05-规范/ # 架构图风格标准.md
二B、5、接口 标准树（2026-05-24 起）
开发文档/5、接口/
├── README.md
├── images/
├── 01-规范与统一层/ # 接口规范.md + 通用服务交互层.md
├── 02-业务对接/ # 存客宝 + 外部网关
├── 03-Hook与微信/ # Hook模块 + 微信矩阵 + Frida 跳转
├── 04-OpenAPI/ # openapi_v3.0.json
└── 05-交互图/ # API架构 HTML
接口文档归类：规范/统一层 → 01；对接方文档 → 02；Hook/微信 → 03；JSON → 04；HTML → 05。
二C、6、后端 标准树（轻量，2026-05-24 起）
开发文档/6、后端/
├── README.md
├── images/
├── 01-服务端/ SDK服务端实现文档.md
├── 02-设备端/ Agent端技能实现文档.md
├── 03-规范汇总/ 后端规范与代码汇总.md
├── docs/ 深度文档（不移动）
├── github核心代码/
└── github-repos/ 克隆库（禁止重组）
二D、8、部署 / 10、项目管理（2026-05-24 起）
8、部署/01-本地环境/ 02-设备Hook/ 03-运维同步/
10、项目管理/ ← 开发进度总表·工作日志·验收 永驻根目录（禁止移动）
02-测试报告/ 03-计划与专项/
二E、1、需求（2026-05-24 起）
1、需求/01-概述/ 02-业务/ 03-调研/ + 修改/ 增量补丁
3、原型/01-规范/ | 4、前端/01～03/ | 7、数据库/01-设计/ 02-规范/
9、手册/ 主手册留根 + 02-操作指南/ 03-验证/ 04-专项/ + images/
新架构资产归类决策树
是 PNG/JPG？
├─ 是 → 整体/SDK/APK？ → images/01-整体总览/
│ 五通道/控制模式？ → images/02-控制通道/
│ 微信/Hook 链路？ → images/03-微信与Hook/
│ 防封？ → images/04-防封/
└─ 否 → 可交互 HTML/Mermaid？ → 04-交互图/
技术选型/数据库？ → 02-技术基座/
Hook/多设备？ → 03-通道与设备/
出图规范？ → 05-规范/
其他总览/模块？ → 01-总览/
三、其他目录 images 约定
| 目录 | images 位置 | 用途 |
|---|---|---|
9、手册 |
9、手册/images/ |
五图 fig01～09、手册配图 |
2、架构 |
2、架构/images/01～04/ |
架构 PNG（见上） |
8、部署/05-测试验收 |
screenshots/、按日期验证目录 |
真机验收，不进架构 images |
各 1～10 目录 |
{目录}/images/doc-headers/ |
文档说明头图（每篇 MD 顶部 ![文档说明]） |
四C、文档说明头图（2026-05-24 起）
目标：每篇主文档 / README / 验收 MD 正文最上方（frontmatter 后）有一张 说明头图，一眼看懂本文档职责。
| 项 | 约定 |
|---|---|
| 位置 | YAML --- 之后、# 标题 之前： |
| PNG 目录 | {1～10、}/images/doc-headers/；根 开发文档/README.md → 开发文档/images/doc-headers/ |
| 生成（首选） | AI 图标横幅（Cursor GenerateImage）→ 卡若AI F09a 04_卡火（火）/火炬_全栈消息/开发文档说明头图/SKILL.md |
| 部署脚本 | 卡若AI …/开发文档说明头图/scripts/deploy_doc_header_ai.py；工作手机首批：8、部署/05-测试验收/scripts/deploy_doc_header_ai.py |
| fallback | generate_doc_header_banners.py（Pillow 扁平条，仅离线无 AI 时用） |
| 风格 | 3:1 横图；图标化扁平科技风（非纯文字条）；顶栏色 ≈ Obsidian 目录色；含中文标题 + 职责图标 |
| 分层 | ① 目录 README → 11 色目录图；② 主题批次（Frida/110/Soul/存客宝）→ 主题图；③ 主文档 → SLUG_MAP 独版 |
| 跳过 | 工作日志.md、追加版 矩阵包、wiki-gitea、github-repos |
新增/改 MD 后：frontmatter + 首段摘要定稿 → MD 内插入  → 新 slug 补进 deploy_doc_header_ai.py 的 SLUG_MAP（或走目录/主题 fallback）→ python3 deploy_doc_header_ai.py。
四D、图片引用 · AI 可读（强制）
问题：Obsidian 粘贴图默认 ![[Pasted image …]] + vault 根目录散落，Cursor/AI 无法从缓存读取。
| 项 | 约定 |
|---|---|
| 禁止 | ![[wikilink]] 引用截图；vault 根目录 Pasted image *.png |
| 存放 | 与 MD 同目录 {文档目录}/images/（或该大类 images/01-子类/） |
| 引用格式 | 标准 Markdown + 本机绝对路径： |
| Obsidian 仍可读 | 绝对路径在 Obsidian 预览中正常显示；人类编辑不受影响 |
| 一键修复 | python3 机擎/scripts/fix_pasted_images.py（扫描 开发文档/，迁移 + 改写） |
| 粘贴后必做 | 粘贴截图 → 立即跑 fix 脚本或手动移入 images/ 并改绝对路径 |
示例：
四、Obsidian 配色规范
Snippet 路径：.obsidian/snippets/workphone-devdoc.css
启用：Settings → Appearance → CSS snippets → workphone-devdoc（已在 appearance.json 登记）
| 路径 | 色值 | 语义 |
|---|---|---|
开发文档/2、架构 |
#1565C0 |
架构根 |
…/01-总览 |
#2E7D32 |
全景 |
…/02-技术基座 |
#6A1B9A |
基建 |
…/03-通道与设备 |
#EF6C00 |
通道 |
…/04-交互图 |
#00838F |
HTML |
…/05-规范 |
#455A64 |
规范 |
…/images |
#78909C |
静态图 |
开发文档/9、手册 |
#1565C0 |
用户手册 |
开发文档/10、项目管理 |
#C62828 |
进度 |
开发文档/1、需求 3、原型 |
#5E35B1 |
需求与原型 |
开发文档/4、前端 5、接口 6、后端 |
#0277BD |
开发与接口 |
开发文档/7、数据库 8、部署 |
#558B2F |
部署与数据 |
开发文档/8、部署/05-测试验收 |
#F9A825 |
部署侧真机验收 |
开发文档/5、接口/06-验收与矩阵 |
#FFB300 |
接口矩阵/开发日志 |
开发文档/1、需求/03-调研/平台分析 |
#AD1457 |
平台调研 |
新建子目录时：在 CSS 追加 .nav-folder-title[data-path="…"] 规则；README frontmatter 写 obsidian-color: "#xxxxxx"。
Cursor 规则：.cursor/rules/workphone.mdc 已引用本 Skill，Agent 开发功能时自动按分层归类。
图谱性能（Obsidian Graph · 强制）
目标：关系图谱只展示 开发文档/ + 机擎/，打开 <3s。
| 配置 | 路径 | 规则 |
|---|---|---|
| 文件排除 | .obsidian/app.json → userIgnoreFilters |
排除 sdk/、vendor/、node_modules/、**/raw/、**/110项功能逐项确认/ |
| 图谱过滤 | .obsidian/graph.json → search |
path:开发文档 OR path:机擎 |
| 轻量 ignore | .obsidianignore |
与上表同步 |
| Smart Connections | .smart-env/smart_env.json → folder_exclusions |
勿索引代码树；show_graph: false |
禁止把 github-repos/、CodeGraph raw/、验收 bulk JSON 放进图谱可见范围。
可选插件：Icon Folder — 可为 01-总览 设 📐、images 设 🖼️，与 CSS 色并存。
四B、标签与关联规范（Obsidian 图谱 · 2026-05-24 起）
目标：开发文档 + 机擎 每篇 MD 可检索、可串联——图谱按 tag 聚类，正文按 related / prev / next 前后跳转。
YAML Frontmatter 必填字段
| 字段 | 说明 | 示例 |
|---|---|---|
tags |
至少 3 项：工作手机 + 顶层目录语义 + doc-type |
[工作手机, 接口, 验收] |
doc-type |
索引 / 主文档 / 验收 / 进度 / SKILL / 参考 |
主文档 |
layer |
相对 开发文档/ 或 机擎/ 的目录层 |
5、接口/06-验收与矩阵 |
parent |
上级 README 的 wikilink | [[5、接口/06-验收与矩阵/README|06-验收与矩阵]] |
related |
3～5 个跨目录相关文档 wikilink | 见下表 |
prev / next |
同层 01- 02- 模块顺序（可选） |
[[01-规范与统一层/README|01-规范与统一层]] |
保留：原有 obsidian-color / SKILL 的 name owner 等字段不删。
跨目录 Hub（写入 related 时优先）
| 文档 | 用途 |
|---|---|
开发文档/README |
总入口 |
开发进度总表 |
进度真源 |
系统架构 |
模块拆解 §3.0 |
工作手机·五图总览与使用手册 |
用户向整合手册 |
机擎/SKILL |
项目管理入口（机擎文档必链） |
文末「🔗 关联导航」块
主文档与 README 文末追加（工作日志.md、110项功能逐项确认/ 历史追加包 不加）：
## 🔗 关联导航
| 方向 | 文档 |
|------|------|
| ↔ 相关 | [[机擎/SKILL|机擎 SKILL]] · [[开发文档/README|开发文档]] · [[开发进度总表]] · [[开发文档结构规范/SKILL|文档结构规范]] · [[阿表/SKILL|阿表 SKILL]] |