test(packaging): 针对打包产物的验收测试套件

.githooks/post-merge

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# MyKnowledge CodeGraph 索引同步
+#
+# git pull / git merge 完成后自动运行 codegraph sync，
+# 把远端合入的新代码增量同步进本地 CodeGraph 索引，
+# 避免探查时用到过期的符号/引用。
+#
+# 启用（一次性，本地配置不进 git）：
+#   git config core.hooksPath .githooks
+#
+# 说明：
+#   - codegraph 不存在时静默跳过（不影响正常合并）。
+#   - sync 失败不阻断流程（仅告警），因为索引过期不会损坏仓库。
+#   - 跳过：git merge --no-verify 不会生效（post-merge 不支持 --no-verify），
+#     如需临时跳过，可手动注释或在调用前 unset 环境变量。
+
+set -u
+
+ROOT="$(git rev-parse --show-toplevel)"
+
+if ! command -v codegraph >/dev/null 2>&1; then
+  echo "→ codegraph 未安装，跳过索引同步"
+  exit 0
+fi
+
+echo "→ 同步 CodeGraph 索引（codegraph sync）..."
+# codegraph sync 的 path 是位置参数（非 --path 选项）；-q 为 git hook 场景设计。
+if codegraph sync -q "$ROOT"; then
+  echo "✓ CodeGraph 索引已更新"
+else
+  echo "⚠ codegraph sync 失败，索引可能过期（不影响仓库），可稍后手动运行 codegraph sync" >&2
+fi
+
+exit 0

.githooks/pre-push

@@ -64,4 +64,19 @@ if [ "$py_ver" != "$js_ver" ] \
 fi
 
 echo "✓ 版本一致：v$py_ver"
+
+# 版本守门通过后，同步 CodeGraph 索引（增量更新，成本低）。
+# codegraph 不存在或 sync 失败时均不阻断 push（仅告警）。
+if command -v codegraph >/dev/null 2>&1; then
+  echo "→ 同步 CodeGraph 索引（codegraph sync）..."
+  # codegraph sync 的 path 是位置参数（非 --path 选项）；-q 为 git hook 场景设计。
+  if codegraph sync -q "$ROOT"; then
+    echo "✓ CodeGraph 索引已更新"
+  else
+    echo "⚠ codegraph sync 失败，索引可能过期（不影响 push），可稍后手动运行 codegraph sync" >&2
+  fi
+else
+  echo "→ codegraph 未安装，跳过索引同步"
+fi
+
 exit 0

.gitignore

@@ -10,6 +10,7 @@ __pycache__/
 .workbuddy/
 .vscode/
 .idea/
+.codegraph/
 *.swp
 *.swo
 *~
@@ -20,6 +21,7 @@ Thumbs.db
 
 # Test / local KB
 .myknowledge_test/
+.pytest_cache/
 
 # Build artifacts
 frontend/index.standalone.html
@@ -29,10 +31,15 @@ frontend/index.standalone.html
 dist-backend/
 /build/
 *.spec
+!myknowledge-backend.spec
 desktop/node_modules/
 desktop/dist/
 desktop/assets/icon.icns
 
+# Enterprise configs (per-customer; not versioned — keep template.json + README.md)
+desktop/enterprises/*.json
+!desktop/enterprises/template.json
+
 # Design artifacts (generated SVG/PNG, not versioned; keep SPEC.md/.md docs versioned)
 docs/designs/**/export/
 docs/designs/**/screenshots/

README.md

@@ -124,6 +124,46 @@ Run tests:
 pytest tests/ -v
 ```
 
+## Desktop App & Enterprise Packaging
+
+### Desktop App
+
+```bash
+cd desktop
+npm install        # once
+npm run release    # default build (all platforms) → desktop/dist/
+```
+
+### Enterprise Customization
+
+Enterprise builds merge per-customer platform whitelists (`enabled`/`display`
+overrides) into the packaged `platforms.json`.
+
+1. **Create the enterprise config** `desktop/enterprises/<name>.json`, modeled
+   on `desktop/enterprises/template.json`.
+   > Enterprise configs are git-ignored (`desktop/enterprises/*.json`, only
+   > `template.json` is tracked) — they never enter the repository.
+2. **Build explicitly** (enterprise configs are never auto-applied):
+
+   ```bash
+   cd desktop
+   npm run release -- --enterprise <name>
+   # or directly:
+   bash scripts/release.sh --enterprise <name>
+   ```
+
+3. **Optional: local shell aliases** (not committed) for one-word builds —
+   one alias per enterprise:
+
+   ```bash
+   # ~/.zshrc
+   alias release:apple='cd /path/to/MyKnowledge_PlatForm/desktop && npm run release -- --enterprise Apple'
+   alias release:xiaomi='cd /path/to/MyKnowledge_PlatForm/desktop && npm run release -- --enterprise Xiaomi'
+   ```
+
+   Then run `release:apple` / `release:xiaomi`. Multiple enterprise configs can
+   coexist in `desktop/enterprises/`; each is selected explicitly by name.
+
 ## Self-Installation
 
 MyKnowledge comes with a complete AI installation guide (`docs/AI-SETUP.md`). Copy it to any MCP-compatible AI agent, and it will:
@@ -137,7 +177,7 @@ MyKnowledge comes with a complete AI installation guide (`docs/AI-SETUP.md`). Co
 
 ## Versioning
 
-- **System version**: defined in `backend/__version__.py` (currently 0.7.6)
+- **System version**: defined in `backend/__version__.py` (currently 0.7.7)
 - **KB version**: git commit hash from `agent-commit.txt` checkpoint
 
 ## License

README.zh.md

@@ -135,9 +135,48 @@ pip install -e .
 pytest tests/ -v
 ```
 
+## 桌面 App 与企业定制打包
+
+### 桌面 App
+
+```bash
+cd desktop
+npm install        # 首次
+npm run release    # 默认打包（全平台）→ desktop/dist/
+```
+
+### 企业定制
+
+企业打包会把每家客户启用的平台白名单（`enabled`/`display` 覆盖）合并进打包
+产物的 `platforms.json`。
+
+1. **创建企业配置** `desktop/enterprises/<企业名>.json`，参照
+   `desktop/enterprises/template.json` 编写。
+   > 企业配置被 git 忽略（`desktop/enterprises/*.json`，只有 `template.json`
+   > 入库）——**企业配置永远不会进代码仓库**。
+2. **显式声明打包**（企业配置不会被自动使用）：
+
+   ```bash
+   cd desktop
+   npm run release -- --enterprise <企业名>
+   # 或直接：
+   bash scripts/release.sh --enterprise <企业名>
+   ```
+
+3. **可选：本地 shell alias**（不入库）实现一键打包——每个企业一条：
+
+   ```bash
+   # ~/.zshrc
+   alias release:apple='cd /path/to/MyKnowledge_PlatForm/desktop && npm run release -- --enterprise Apple'
+   alias release:xiaomi='cd /path/to/MyKnowledge_PlatForm/desktop && npm run release -- --enterprise Xiaomi'
+   ```
+
+   之后直接 `release:apple` / `release:xiaomi`。多个企业配置可共存于
+   `desktop/enterprises/`，按名字显式选择。
+
 ## 版本
 
-- **系统版本**：定义在 `backend/__version__.py`（当前 0.7.6）
+- **系统版本**：定义在 `backend/__version__.py`（当前 0.7.7）
 - **知识库版本**：从 `agent-commit.txt` checkpoint 读取的 git commit hash
 
 ## 许可

backend/AiClientConfig/agents/MyKnowledge-agent-Enchante.md

@@ -0,0 +1,15 @@
+# MyKnowledge Agent
+
+你是 MyKnowledge 本地知识库（Markdown + Git）的专业 Agent，通过 MyKnowledge MCP 工具读写文档并维护知识库结构。
+
+## 边界与规范
+
+- 一切操作仅限本地知识库 root 内；只允许在 `common-knowledge/`、`projects/`、`archive/` 开头的路径下写入；禁止 `..` 路径穿越与绝对路径。
+- 写入会自动重建父级 readme 并提交 git；不要手动伪造 frontmatter，需保持文档为合法 Markdown。
+- 不删除或改名已有文档的 frontmatter 必需字段；新增字段安全，删改字段需评估影响。
+- 只操作本地知识库，不访问网络、不改写平台自身配置。
+- 遇到不确定的写入（覆盖、删除、改名），先说明后果并征得同意再执行。
+
+## 工具
+
+你的全部工具来自 **MyKnowledge** 这个 MCP server（操作本地知识库）：用 `mcp_get_tool_description` 查看 MyKnowledge 提供的工具清单与用法，用 `mcp_call_tool` 调用；结构异常时用 `maint__knowledgebase_diagnose` 定位。

backend/AiClientConfig/agents/MyKnowledge-agent.md

@@ -13,17 +13,20 @@ MyKnowledge 是一个纯 Markdown + Git 的本地知识库平台。你的职责
 
 - **检索与导航**：`nav__list_dir` / `nav__get_document` / `nav__find` — 定位目录、读取文档、按条件查找。
 - **文档写入**：`write__create_document` / `write__update_document` — 新建 / 更新文档（自动生成 id 与 frontmatter）。
-- **结构维护**：`maint__knowledgebase_diagnose` — 检测知识库结构问题。
+- **未提交检查**：`maint__check_uncommitted` — 检查工作区是否有未 commit 的改动（用户前端 REST 保存的临时草稿）。
+- **结构健康**：`maint__knowledgebase_diagnose` — 检测知识库结构问题（低频例行）。
 - **工具能力**：`mcp_get_tool_description` / `mcp_call_tool` — 了解并使用各工具。
 - **回滚与恢复**（如可用）：`maint__list_trash` / `write__restore_document` — 处理误删恢复。
 
 ## 工作流程
 
-1. **先建立上下文**：操作前先用 `nav__get_document` 读取知识库根 readme，了解整体结构，避免凭猜测定位。
-2. **定位再写入**：写操作前先用 `nav__list_dir` / `nav__find` 确认目标路径存在且正确，不盲目新建目录或覆盖文档。
-3. **写入即维护**：`write__create_document` / `write__update_document` 会自动重建父级 readme 并提交 git，无需手动处理。
-4. **诊断兜底**：结构异常（缺 readme、路径错乱）时用 `maint__knowledgebase_diagnose` 定位问题。
-5. **完成报告**：每次任务结束，向使用者汇报：改动了哪些文档 / 目录、是否触发重建与提交、遇到的边界问题。
+1. **先查未提交改动**：介入任务前先调用 `maint__check_uncommitted`，了解工作区是否有未 commit 的临时草稿。这是「待处理清单」——只做一句话播报，不阻塞、不主动追问，等用户明确要求「提交 / 整理」时才走写入流程。避免覆盖或遗漏用户已在前端保存但未正式化的内容。
+2. **低频健康检查**：每个会话开始时自问「距上次 `maint__knowledgebase_diagnose` 是否已超过 1 小时」，超时才跑一次；1 小时内不重复，避免每次对话都全库扫描。有结构问题（缺 readme、路径错乱）时向用户简要播报，不擅自修复。
+3. **先建立上下文**：操作前先用 `nav__get_document` 读取知识库根 readme，了解整体结构，避免凭猜测定位。
+4. **定位再写入**：写操作前先用 `nav__list_dir` / `nav__find` 确认目标路径存在且正确，不盲目新建目录或覆盖文档。
+5. **写入即维护**：`write__create_document` / `write__update_document` 会自动重建父级 readme 并提交 git，无需手动处理。
+6. **诊断兜底**：结构异常（缺 readme、路径错乱）时用 `maint__knowledgebase_diagnose` 定位问题。
+7. **完成报告**：每次任务结束，向使用者汇报：改动了哪些文档 / 目录、是否触发重建与提交、遇到的边界问题。
 
 ## 路径与写入规范
 

backend/AiClientConfig/agents/frontmatter.json

@@ -7,7 +7,7 @@
       "frontmatter": {
         "name": "MyKnowledge 知识管理专家",
         "description": "MyKnowledge 知识管理平台协作 Agent：通过 MCP 检索与维护本地知识库",
-        "tools": "mcp_get_tool_description, mcp_call_tool, nav__list_dir, nav__get_document, nav__find, write__create_document, write__update_document, maint__knowledgebase_diagnose",
+        "tools": "mcp_get_tool_description, mcp_call_tool, nav__list_dir, nav__get_document, nav__find, write__create_document, write__update_document, maint__knowledgebase_diagnose, maint__check_uncommitted",
         "model": "inherit"
       }
     },
@@ -16,7 +16,7 @@
       "frontmatter": {
         "name": "MyKnowledge 知识管理专家",
         "description": "MyKnowledge 知识管理平台协作 Agent：通过 MCP 检索与维护本地知识库",
-        "tools": "mcp_get_tool_description, mcp_call_tool, nav__list_dir, nav__get_document, nav__find, write__create_document, write__update_document, maint__knowledgebase_diagnose",
+        "tools": "mcp_get_tool_description, mcp_call_tool, nav__list_dir, nav__get_document, nav__find, write__create_document, write__update_document, maint__knowledgebase_diagnose, maint__check_uncommitted",
         "model": "inherit",
         "agentMode": "manual",
         "enabled": true,

backend/AiClientConfig/hooks/WorkBuddy.json

@@ -4,10 +4,10 @@
   "supports_hooks": true,
   "event": "PreToolUse",
   "matcher": "Bash|Write|Edit",
-  "matcher_note": "与 Claude Code 同协议：PreToolUse 按工具名触发，必须同时覆盖 Bash 与 Write/Edit（否则 file_write 拦截分支死代码）。MCP 调用由 hooks.py 内部放行。",
-  "command": "curl -s -X POST http://127.0.0.1:8080/hooks/pre-tool-use -H 'Content-Type: application/json' -d '$CLAUDE_TOOL_USE_INPUT'",
-  "protocol": "同 Claude Code：环境变量 $CLAUDE_TOOL_USE_INPUT 传 JSON，stdout 输出 JSON 决策。",
+  "matcher_note": "与 Claude Code 同协议：PreToolUse 按工具名触发，必须覆盖 Bash 与 Write/Edit（否则 file_write 拦截分支死代码）。MCP 调用由 hooks.py 内部放行。",
+  "command": "curl -s -X POST http://127.0.0.1:8080/hooks/pre-tool-use -H 'Content-Type: application/json' -d @-",
+  "protocol": "WorkBuddy 与 Claude Code 的 PreToolUse hook 协议完全同构（2026-08-19 经官方/实测确认）：payload 走 stdin（CodeBuddy CLI 与 WorkBuddy 同源引擎，官方文档「Hook scripts receive JSON-formatted input data via stdin」）；读 hookSpecificOutput.permissionDecision 做 allow/deny（另支持 ask 三态，我们只回 allow/deny 兼容）；退出码 0=放行(按 stdout JSON)/1=非阻断放行/2=阻断/其它=放行。无 $WORKBUDDY_TOOL_USE_INPUT 环境变量传 payload。后端不依赖 tool_use_id/call_id（只读 tool_name/tool_input/cwd），字段名差异无影响。",
   "exit_code_deny": 2,
   "fail_open": true,
-  "notes": "写入 ~/.workbuddy/settings.json 的 hooks.PreToolUse。命令与 ClaudeCode 相同。"
+  "notes": "写入 ~/.workbuddy/settings.json 的 hooks.PreToolUse（非 ~/.claude/），改完须完全重启 WorkBuddy 才加载。命令与 ClaudeCode 相同（-d @- 从 stdin 读 payload）。阻断判定靠 stdout JSON 的 permissionDecision 而非 curl 退出码；后端不可达时 curl 退出非 0 → 放行（fail-open），符合审计日志场景。"
 }