codewiki-plus 5.16.2__tar.gz → 5.16.4__tar.gz

codewiki_plus-5.16.4/.codebuddy/memory/2026-10-22.md

@@ -0,0 +1,15 @@
+# 2026-10-22
+
+## CodeBuddy SessionEnd 采集竞态修复（任务：日常维护）
+- 根因（内网电脑实证）：wrapper `capture_session_end.py` DETACHED_PROCESS fire-and-forget 与 IDE Finalize 清理 `messages/*.json` 竞态；展开失败后 `_load_transcript` 把元数据列表原样返回 → "no usable turns" 被 DEVNULL 吞掉，零痕迹。
+- 修复（`codewiki/mcp/_ide_hook.py`，未 commit）：
+  1. `_wait_for_message_files`：index 是 CodeBuddy 形状但所有 message 文件缺失时，指数退避等待落盘（0.1s 起、8 次 ~10s 预算）；部分存在则不等待。
+  2. `_is_codebuddy_index`：展开失败返回 None，不再让无正文元数据漏成假 turns（list/dict 两分支）。
+  3. `_log_capture_event`：fail-open 追加 `repowiki/.meta/hook_capture.log`，静默丢弃可诊断。
+- 验证：新增 5 回归测试；聚焦 46 + 关联 105 全过；ruff/format 干净；mypy 与基线一致（3 存量）。
+- 5.16.1 无此修复，需随下版本发布；内网电脑升级后生效。
+
+## v5.16.2 发布完成（任务：发版本）
+- 发布内容即上述竞态修复（fix 提交 b348570）+ bump 342023f；PR #42 CI 绿后合并（merge commit b42da32）；Release id 420621725（tag 远端自动打）；PyPI uv publish 直接成功（TLS 未被干扰），JSON API 核对 latest=5.16.2（whl 1,047,766 B + sdist 15,850,122 B）。
+- 闸门：pytest 1299 passed/3 skipped（18:17）；ruff 全过。
+- 教训：bump 提交混入了会话前已暂存的 repowiki 任务记忆文件（git add 前未清 index）；uv publish 成功时 stdout/stderr 可能被控制台吞掉，输出须落文件核对。

codewiki_plus-5.16.4/.codebuddy/memory/2026-10-24.md

@@ -0,0 +1,18 @@
+# 2026-10-24
+
+## 日常维护：24 个技能 disable-model-invocation 评估
+- 用户发现 codewiki setup/sync-skills 生成的 24 个技能全部 disable-model-invocation: true（ADR-0019 刻意设计，sync_skills.py:65 模板硬编码），要求评估哪些可放开自动调用。
+- 评估结论：建议放开 8 个——只读分析类 6 个（search-wiki/impact-review/change-review/architecture-review/quality-check/cross-service-trace）+ 带确认闸门 2 个（ingest-note/task-workflow）；保持手动 16 个（破坏性、一次性装机、重型流水线、Doctrine 明令不自动的 distill/consolidate、知识生产后段 skill-creator/promote-note）。
+- 附带提醒：放开的技能 description 需从「工作流摘要」改写为「触发条件」口径，否则误触发率高；实现需 _PROMPT_REGISTRY 加 auto 元数据 + 模板条件渲染。待用户确认后实施。
+
+## 日常维护：7 个技能自动触发改造已实施
+- 用户指定清单（与我建议的 8 个不同）：search-wiki、ingest-note、distill-conversations、task-workflow、consolidate-knowledge、skill-creator、promote-note 共 7 个放开；impact-review/change-review/architecture-review/quality-check/cross-service-trace 保持手动。
+- 实现：_PROMPT_REGISTRY 加 "auto": True 元数据；sync_skills.py 模板条件渲染（auto → `# model-invocable` 注释行替代 disable-model-invocation），manual_hint/auto_hint 双态文案；静态 codewiki-setup 不动。
+- 验证：聚焦 47 passed + 关联 48 passed，ruff/mypy 干净；已对本仓重跑 sync-skills，三宿主（codebuddy/qoder/trae）24 技能落盘生效。
+- 注意：distill-conversations 放开与 Doctrine「不自动蒸馏」边界冲突，用户明确要求，需观察误触发。未 commit。
+
+## 2026-10-25 补充：已提交推送
+- description 触发条件口径改写完成（7 技能 × zh/en = 14 处）；OCR 评审发现 manual_hint 占位符双态语义漂移，已改名 trigger_hint 修复。
+- commit 484b775 已推送 develop（含暂存区既有的 5 个 repowiki 蒸馏产物一并带入）。验证：47 passed + 1 skipped，lint 干净。
+
+

codewiki_plus-5.16.4/.codebuddy/memory/2026-10-26.md

@@ -0,0 +1,24 @@
+# 2026-10-26
+
+## 发版本任务补蒸馏（distill-worker-5163）
+- Mode C 清空任务「发版本」积压：1 条对话（conv-@command-windows-python-release-发布新版本-5.16.2）。
+- 产出 1 条草稿笔记：`repowiki/notes/2026-10-26-发版时-tag-区间无新提交发布内容可能在未提交的工作区改动里提交只-add-具体文件.md`（procedure，priority 75）。
+- 冲突去重：与「显式 pathspec 提交」笔记部分重叠，判定 store 并在正文引用既有笔记。
+- submit 返回 skill_hint（worth_compiling=true），已原样汇报给 team-lead，未执行编译。
+
+## v5.16.3 发布完成（发版本任务）
+- 版本判定：v5.16.2 后 1 个 feat（484b775 技能自动调用）→ 用户指定 patch bump 5.16.3。
+- 闸门：pytest 1303 passed/3 skipped；ruff check 全过；4 个变更 py 文件 format 全过（全量 --check . 会报 repowiki/conversations/*.md 内嵌代码块，不在 CI 范围）。
+- GitHub：bump 683c129 → PR #43 CI 绿合并（merge 4c2c7d5）→ Release id 423793301（target_commitish 方式，tag 远端自动打）。
+- PyPI：uv publish 直接成功（TLS 未被干扰），JSON API 核对 latest=5.16.3（whl 1,048,500 B + sdist 17,858,556 B）。
+- 坑：git add -A 误暂存 .scratch/、docs/whitepaper/ 等未跟踪文件（157 文件 8 万行），reset 后改用 `git add -u` + `repowiki/conversations/` 精确暂存。
+
+## caw 订阅模式移除（发版本任务）
+- 用户决策：工具不考虑订阅模式。删除 caw_backend.py / caw_toolkit.py / coding-agent-wrapper 依赖，清理 7 处引用分支（backend/config/config_manager/legacy_tools/2 测试），同步 README 与 CodeWiki介绍.md 口径。
+- 验证：全量 pytest 1359 passed / 2 skipped（Windows 全绿，fcntl 环境性失败随 caw 删除消失）；7 文件 ruff 全过。
+- 提交 2d2e1e0 推送 develop。OCR 评审通过（发现 2 个文档口径滞后已修）。
+- 注意：ide_config.py:81 的 "claude-code" 是 IDE hook 注册表，与订阅模式无关，保留。
+
+## 笔记确认 + 技能编译（发版本任务）
+- confirm_note：《发版时 tag 区间无新提交…》→ stable（human:iamwangbao-163-com）。
+- skill_creator UPDATE（反碎片化，非新建）：windows-python-release 技能折入 4 处增量——①新增步骤 0「判定发布内容与 bump 级别」（tag 区间无提交先查工作区）；②步骤 2 提交纪律（只 add 具体文件、fix 与 bump 分 commit）；③步骤 3 闸门顺序细化；④步骤 6 补 target_commitish 自动打 tag。草稿已落 repowiki/skills/（revisions=4），已 install 到 `.codebuddy/skills/windows-python-release/`（hash 8d681945…，IDE 下次扫描生效）。

codewiki_plus-5.16.4/.codebuddy/skills/codewiki-consolidate-knowledge/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-consolidate-knowledge
+description: "lint_wiki 或 wiki_stats 提示 notes_since_last_consolidation 超阈值、出现 aggregation_hint，或用户要求「聚合笔记」时使用（执行前须先询问用户确认）。把已确认笔记聚合为 L2 工作方法场景块（wiki/scenarios/）：prepare 获取待聚合笔记与容量预警 → 撰写/更新场景块 → reject_note 退役被吸收笔记 → submit 记录溯源并归零计数器。"
+# model-invocable
+---
+
+# 知识聚合（L2 场景块）
+
+lint_wiki 或 wiki_stats 提示 notes_since_last_consolidation 超阈值、出现 aggregation_hint，或用户要求「聚合笔记」时使用（执行前须先询问用户确认）。把已确认笔记聚合为 L2 工作方法场景块（wiki/scenarios/）：prepare 获取待聚合笔记与容量预警 → 撰写/更新场景块 → reject_note 退役被吸收笔记 → submit 记录溯源并归零计数器。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="consolidate-knowledge", arguments={"repo_path": "."})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-consolidate-knowledge 触发。

codewiki_plus-5.16.4/.codebuddy/skills/codewiki-distill-conversations/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-distill-conversations
+description: "检测到 repowiki/raw/ 存在未蒸馏的已采集对话积压时使用（如会话开始提示 pending_raw_count > 0）。把已采集对话蒸馏为双轨产物：notes（通用经验笔记）与 memories（任务进度记忆）。宿主 Agent 充当 LLM：distill_conversation(mode=prepare) 取 transcript → Agent 提取知识 → mode=submit 交回做去重/草稿入库/记忆落盘/评审。全程本地闭环，蒸馏产出的笔记须 confirm_note 确认。"
+# model-invocable
+---
+
+# 蒸馏对话提取记忆和经验
+
+检测到 repowiki/raw/ 存在未蒸馏的已采集对话积压时使用（如会话开始提示 pending_raw_count > 0）。把已采集对话蒸馏为双轨产物：notes（通用经验笔记）与 memories（任务进度记忆）。宿主 Agent 充当 LLM：distill_conversation(mode=prepare) 取 transcript → Agent 提取知识 → mode=submit 交回做去重/草稿入库/记忆落盘/评审。全程本地闭环，蒸馏产出的笔记须 confirm_note 确认。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="distill-conversations", arguments={"repo_path": "."})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-distill-conversations 触发。

codewiki_plus-5.16.4/.codebuddy/skills/codewiki-ingest-note/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-ingest-note
+description: "完成重要决策、多步调试定位到根因、被用户纠正/吐槽、发现可复用模式后，需要把经验沉淀进知识库时使用。将设计决策、经验教训、架构 rationale、踩坑记录等归档为 8 种笔记类型，自动 BM25 索引，可通过 query_wiki 检索。"
+# model-invocable
+---
+
+# 经验知识归档
+
+完成重要决策、多步调试定位到根因、被用户纠正/吐槽、发现可复用模式后，需要把经验沉淀进知识库时使用。将设计决策、经验教训、架构 rationale、踩坑记录等归档为 8 种笔记类型，自动 BM25 索引，可通过 query_wiki 检索。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="ingest-note", arguments={"repo_path": ".", "note_type": "<note_type>"})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-ingest-note 触发。

codewiki_plus-5.16.4/.codebuddy/skills/codewiki-promote-note/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-promote-note
+description: "wiki_stats 出现 promotion_candidates 候选、某条 stable 笔记被反复采纳，或用户要求把笔记转正时使用。把候选笔记去个人化重写为正式 wiki 页面：类型路由（pitfall/bug_fix/workaround → query，lesson/decision/architecture → concept）→ write_doc_file 写新页面（必须 draft 状态，写完提醒 confirm）→ edit_doc_file 回标原笔记 metadata.promoted_to。原笔记不删除不降级，保留作审计轨迹锚点。"
+# model-invocable
+---
+
+# 笔记晋升为正式 wiki 页面
+
+wiki_stats 出现 promotion_candidates 候选、某条 stable 笔记被反复采纳，或用户要求把笔记转正时使用。把候选笔记去个人化重写为正式 wiki 页面：类型路由（pitfall/bug_fix/workaround → query，lesson/decision/architecture → concept）→ write_doc_file 写新页面（必须 draft 状态，写完提醒 confirm）→ edit_doc_file 回标原笔记 metadata.promoted_to。原笔记不删除不降级，保留作审计轨迹锚点。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="promote-note", arguments={"note_file": "<note_file>", "repo_path": "."})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-promote-note 触发。

codewiki_plus-5.16.4/.codebuddy/skills/codewiki-search-wiki/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-search-wiki
+description: "需要检索 Wiki 知识库时使用：编码前查模块文档与架构约定、做决策前查已有 decision 笔记、改文件前查该文件的历史教训。策略指引：BM25 搜索、图谱扩展、深度阅读。"
+# model-invocable
+---
+
+# 知识库搜索
+
+需要检索 Wiki 知识库时使用：编码前查模块文档与架构约定、做决策前查已有 decision 笔记、改文件前查该文件的历史教训。策略指引：BM25 搜索、图谱扩展、深度阅读。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="search-wiki", arguments={"query": "<query>"})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-search-wiki 触发。

codewiki_plus-5.16.4/.codebuddy/skills/codewiki-skill-creator/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-skill-creator
+description: "用户要求「生成技能」「把经验编成 SKILL」，或 skill_hint 提示某笔记反复被采纳适合编译时使用。把已确认知识（场景块 + stable 笔记 + 技能 open issues）编译为 SKILL.md 行为指令草稿（repowiki/skills/，两区制草稿区：进索引进 lint、不生效）：prepare 取候选素材/冲突预检/容量预警/写作规范 → Agent 撰写 → submit 校验落盘并写双向溯源。install/retire 为后续工单。"
+# model-invocable
+---
+
+# 技能编译（SKILL.md 草稿区）
+
+用户要求「生成技能」「把经验编成 SKILL」，或 skill_hint 提示某笔记反复被采纳适合编译时使用。把已确认知识（场景块 + stable 笔记 + 技能 open issues）编译为 SKILL.md 行为指令草稿（repowiki/skills/，两区制草稿区：进索引进 lint、不生效）：prepare 取候选素材/冲突预检/容量预警/写作规范 → Agent 撰写 → submit 校验落盘并写双向溯源。install/retire 为后续工单。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="skill-creator", arguments={"repo_path": "."})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-skill-creator 触发。

codewiki_plus-5.16.4/.codebuddy/skills/codewiki-task-workflow/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-task-workflow
+description: "用户表示「继续上一个任务」「接着上次的干」等跨会话延续工作，或需要创建/关联任务、按 task_id 检索任务上下文时使用。覆盖创建/关联任务、采集对话绑定 task_id、蒸馏时双轨产出笔记与任务记忆、按 task_id 检索与聚合。"
+# model-invocable
+---
+
+# 任务记忆工作流
+
+用户表示「继续上一个任务」「接着上次的干」等跨会话延续工作，或需要创建/关联任务、按 task_id 检索任务上下文时使用。覆盖创建/关联任务、采集对话绑定 task_id、蒸馏时双轨产出笔记与任务记忆、按 task_id 检索与聚合。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="task-workflow", arguments={"repo_path": "."})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-task-workflow 触发。

codewiki_plus-5.16.4/.codebuddy/skills/windows-python-release/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: windows-python-release
+description: 当要手动发布 Python 包（codewiki-plus）到 PyPI 并建 GitHub Release 时——CI 不发布、Windows 控制台为 GBK、可能无 gh CLI、本机网络对 upload.pypi.org 的 Python TLS 握手有干扰——先核对 tag 区间与工作区未提交改动定 bump 级别，再按 8 步主干执行：同步四处版本→bump 提交（只 add 具体文件）→聚焦+ruff+全量闸门→清 dist 构建→PR 合并 main→tag merge commit 建 Release→uv publish（TLS 超时则 curl.exe 直传）→PyPI JSON API 核对
+---
+
+## 工作场景
+
+手动发布 Python 包（`codewiki-plus`）到 PyPI 并创建 GitHub Release。**CI 只跑测试与 lint，不负责构建与发布**（`.github/workflows/ci.yml:13-74`），因此发布主干没有脚本承载，必须按序手工执行。Windows 控制台默认 GBK，环境可能无 gh CLI。
+
+## 适用条件
+
+- 发布是手动流程，仓库无发布脚本
+- 提交信息或 Release 正文含中文/emoji
+- 环境无 gh CLI / 未配置 GH_TOKEN，但 git credential manager 已保存凭据
+
+## 核心 SOP
+
+按序执行 8 步，**每步有判定点，不通过就停，不要带着问题往下走**。
+
+0. **判定发布内容与 bump 级别**：`git log <上一tag>..HEAD --oneline` 看提交，**同时 `git status --short` + `git diff --stat` 核对工作区未提交改动**——tag 区间无新提交 ≠ 没有发布内容，发布内容可能全在未提交的工作区里（v5.16.2 实例：log 为空但 fix 改动全在工作区）。据实际内容定 patch/minor bump。
+   判定点：发布内容清单明确，bump 级别有依据。
+
+1. **同步四处版本引用**：`pyproject.toml`（`version`）、`codewiki/__init__.py`（`__version__`）、`uv.lock`（用 `uv lock` 刷新，勿手改）、`codewiki/mcp/server.py`（`version=__version__` 注入，勿手写常量）。CLI 与 actor id 也从 `__version__` 读取，自动跟随。
+   判定点：四处版本字符串完全一致。
+
+2. **提交 bump 并推送 develop**：消息 `chore: bump version to X`；推 `origin develop`。
+   判定点：`git show` 确认版本改动齐全。
+   ⚠️ 中文提交信息用 `git commit -F <utf8 文件>`，**不要用 `-m`**（GBK 破坏，乱码或拆词）。
+   ⚠️ **只 add 具体文件**：fix 改动与版本 bump 分两个 commit；工作区混着的 repowiki 产物等非发布文件不入库。`git add -A` 会扫入未跟踪的 `.scratch/`、草稿文档等无关文件（v5.16.3 实例：误暂存 157 文件 8 万行），用 `git add -u` + 显式路径精确暂存。
+
+3. **发布闸门（按序）**：聚焦测试（改动模块，秒级）→ `ruff check` / `ruff format --check`（本次变更的 py 文件，与 CI 增量 lint 同口径）→ 全量 `pytest -q`。
+   判定点：无失败用例，无 lint 错误。
+   ⚠️ 全量 `ruff format --check .` 会报 repowiki/conversations/*.md 内嵌代码块——不在 CI Lint 范围，按 CI 同口径逐文件验证即可。
+
+4. **构建并清理产物**：`uv build`；发布前**清 `dist/`** 或只精确指定本次产物。
+   判定点：`dist/` 下只剩本次版本的 wheel 与 sdist。
+   ⚠️ 不清 `dist/` 会连带上传旧产物（5.6.0 发布时残留 6 个）。
+
+5. **合并 main**：建 PR develop→main（无 gh CLI 时用 Python `subprocess` 调 `git credential fill` 取凭据再调 REST API，请求体显式 UTF-8）；轮询 head sha 的 **check-runs**（不是 commit status）等 CI 绿后合并。
+   判定点：PR merged，main 含 bump commit。
+
+6. **打 tag 并建 GitHub Release**：lightweight tag `vX.Y.Z` 打在 **PR merge commit 上（main 分支）**——Release 应反映 main 的事实状态；不要打在 develop 的 bump commit 上（v5.12.0 旧做法，与 Release 所属分支不一致）。Release 正文经 REST API 创建，显式 UTF-8；也可用 Release API 的 `target_commitish` 让远端自动打 tag。
+   ⚠️ Release 正文乱码**不可逆**（UTF-8 被按 GBK 解码写入，字符永久丢失），只能基于 `git log` 事实重写。
+   ⚠️ 给 `git credential fill` 喂 stdin 不用 PowerShell 管道（stdin 常为空、引号被破坏），用 `subprocess` 精确传字节；凭据只留进程内。
+
+7. **发布到 PyPI**：优先 `uv publish dist/codewiki_plus-<version>*`（精确指定，默认传 dist/ 全部）。
+   **token 来源：Windows 凭据管理器（keyring）**——`keyring.get_password('pypi', 'upload')`，首次配置：`keyring.set_password('pypi', 'upload', '<token>')`。**不要让用户把 token 粘贴到对话里**（本仓库 4 次泄露事故全部源于此），也不要写进仓库内任何文件（gitignore 不是安全边界，`.codebuddy/` 是被跟踪目录）。
+   ⚠️ **本机网络对 upload.pypi.org 的 Python OpenSSL TLS 握手会被干扰**：uv publish / twine / requests 全部连接超时（TCP 通、curl 秒通）。绕法：curl.exe（schannel 栈）直传 legacy API——Python 从 whl 的 `*.dist-info/METADATA`、sdist 的 `PKG-INFO` 提取元数据构造完整表单（`:action=file_upload`、`protocol_version=1`、`filetype`、`pyversion` + 全部元数据字段 + `description` 正文），写 curl `-K` 配置文件（`form-string`，命令行会超长），`-u __token__:<token>` POST。**digest 字段名是 `sha256_digest`**（不是 `digests_sha256`，400 报 missing digest）。token 经参数传进程内，用完删临时文件。
+   ⚠️ **email.parser 提取元数据时 `Message.keys()` 对重复头返回 N 次**（如 4 个 `Project-URL`），循环内再 `get_all(key)` 会产生 N×N 重复字段（v5.13.1 时 project_urls 重复 16 条被 400 拒绝）。遍历前必须对 key 去重。
+
+8. **核对真实上传**：`https://pypi.org/pypi/codewiki-plus/json` 查最新版本（JSON API 有缓存延迟，可直接查 `/pypi/codewiki-plus/<version>/json`）。
+   判定点：API 返回版本 == 目标版本，双产物 size 正确。
+
+## 判断逻辑
+
+- **主干优先**：先有完整流程，避坑是各步的注解，不是流程的替代品。缺任何一步（尤其是 3 闸门与 8 核对）都不算发布完成。
+- **tag 区间无新提交 ≠ 无事可发**：发布内容可能全在未提交的工作区改动里，先看 `git status` 再下结论（依据: notes/2026-10-26-发版时-tag-区间无新提交发布内容可能在未提交的工作区改动里提交只-add-具体文件.md 的「tag 区间无提交容易被误判为无事可发」）。
+- 乱码/拆词/stdin 失效同源：都是 cmd/PowerShell 中间层破坏参数与编码。统一绕法是「落文件 / 精确 subprocess」，不是加转义。
+- TLS 握手超时先做栈归因：TCP 通 + curl（schannel）通 + Python requests 超时 → 是 OpenSSL 栈被网络层干扰，换传输栈（curl.exe）而不是加超时重试。
+- PyPI 只增不改会幂等跳过已存在文件，但这是侥幸，不是安全网。
+
+## 禁忌与反模式
+
+- 不要 `git commit -m "中文"`
+- 不要 `git add -A` 一把梭——只 add 具体文件，fix 与 bump 分 commit
+- 不要不清 `dist/` 就直接 `uv publish`
+- 不要跳过闸门（步骤 3）或发布后核对（步骤 8）
+- 不要用 PowerShell 管道或 `cmd /c echo` 给 `git credential fill` 喂 stdin
+- 不要试图反向还原 GBK 乱码文本（字符已丢失，只能重写）
+- PyPI 上传超时不要盲目加超时重试——先区分是读取慢（加超时有用）还是 TLS 握手被掐（换 curl.exe）
+- 不要把 PyPI token 写进任何落盘文件后不清理
+- 不要把 PyPI token 存进仓库内文件（含 gitignore 的文件）——统一走 keyring（Windows 凭据管理器）
+- 不要让用户把 token 粘贴到对话里——对话采集 hook 会把它原样写进 repowiki/conversations/ 并随提交推送
+
+依据: notes/2026-09-10-codewiki-手动发布完整流程同步四处版本测试build清distpublishrelease核对.md 的「7 步主干与每步判定点」；wiki/scenarios/发布与依赖治理方法.md 的「dist 残留被一并上传」「Release 正文乱码不可逆」「Windows 参数与 stdin 编码统一绕法」；任务「发版本」v5.13.0 发布实操（2026-09-23）：TLS 握手干扰归因与 curl.exe 绕法、sha256_digest 字段名、tag 打在 merge commit 的约定；notes/2026-10-26-发版时-tag-区间无新提交发布内容可能在未提交的工作区改动里提交只-add-具体文件.md 的「tag 区间无提交先查工作区」「只 add 具体文件、fix 与 bump 分 commit」「闸门顺序聚焦→ruff→全量」

codewiki_plus-5.16.4/.gitignore

@@ -0,0 +1,159 @@
+config/agent_config.yaml
+tool/add_header.sh
+
+# Python
+.venv
+venv/
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Tests
+.pytest_cache/
+# pytest basetemp (configured in pyproject): local-only, never commit
+.pytest-tmp/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+
+# Jupyter
+*.ipynb
+.ipynb_checkpoints
+
+# Project specific
+output/
+data/
+src/output/
+repo_data/
+docs/.cache/
+repowiki/.meta/retrieval_stats.db
+# T2 (团队方案): 共享遥测事件流 .meta/telemetry/ 默认入库；本机退化模式
+# (conventions.telemetry.enabled: false) 的写入位置不入库
+repowiki/.meta/telemetry-local/
+# P2-3: 原子写残留（崩溃/被杀时 .tmp.<pid>.<tid> 不及清理）与 sidecar 锁文件
+# 是本机瞬态产物，永远不入库（历史误提交的 Administrator.jsonl.tmp.19748 即此类残留）
+repowiki/.meta/telemetry/*.tmp.*
+repowiki/.meta/telemetry/*.lck
+# T3 (团队方案): search_index.json 是秒级可重建的本机派生索引——
+# 入库只会制造最大的全量重写冲突面，且可能固化过期索引（T1 自愈兜底重建）
+repowiki/.meta/search_index.json
+# Team-layout Phase 1 (D1): 可重建派生物不入库（详见 docs/团队化文件冲突治理与同步策略设计方案.md）
+repowiki/wiki/index.md
+repowiki/.meta/edit_history.json
+repowiki/.meta/metadata.json
+repowiki/.meta/module_tree.json
+repowiki/.meta/symbol_map.json
+repowiki/.meta/project.json
+repowiki/.meta/overview_refs.json
+repowiki/.meta/aggregate_state.json
+repowiki/.meta/source_registry.json
+# ADR-0020: generation job ledger — local progress state, rebuilt on next run
+repowiki/.meta/job.json
+# 仓库本地身份钉（resolve_user_id 的 pin 环节）：每台机器各自的身份，绝不该入库
+repowiki/.meta/user_id
+repowiki/.meta/task_bindings/
+repowiki/tasks/.index.json
+repowiki/distill-jobs.json
+# team-memory fusion: raw/ is a transient staging area for captured
+# conversations (deleted after distillation) — never commit it.
+repowiki/raw/
+
+# Environment variables
+.env*
+*.env
+**/.env
+**/.env.*
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.log
+*.bak
+# KnowledgeStore lock files (centralized under repowiki/.meta/locks/; *.lck
+# also covers legacy co-located sidecars)
+repowiki/.meta/locks/
+*.lck
+.trash/
+.codewiki/
+.workbuddy/
+# CodeBuddy team-member runtime state (mailbox/history JSON) — transient, never commit
+.codebuddy/teams/
+
+# Qoder IDE plugin skills (not part of this repo); codewiki-* 为 sync-skills 生成快照，入库（ADR-0019）
+.qoder/skills/*
+!.qoder/skills/codewiki-*/
+# better-harness 审查产物与 agent-lint 报告：秒级可重跑的工具输出，按 D1
+# 「可重建派生物不入库」排除（findings 结论已沉淀进文章与 repowiki 笔记）
+.qoder/better-harness-runs/
+.qoder/agent-lint.json
+# Team-layout Phase 1: 可重建派生物不入库（D1，详见 docs/团队化文件冲突治理与同步策略设计方案.md）
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/wiki/index.md
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/.meta/edit_history.json
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/.meta/metadata.json
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/.meta/module_tree.json
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/.meta/symbol_map.json
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/.meta/project.json
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/.meta/overview_refs.json
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/.meta/aggregate_state.json
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/.meta/source_registry.json
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/.meta/task_bindings/
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/.meta/locks/
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/tasks/.index.json
+.pytest-tmp/test_still_allows_workspace_ro0/repowiki/distill-jobs.json
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/wiki/index.md
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/.meta/edit_history.json
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/.meta/metadata.json
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/.meta/module_tree.json
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/.meta/symbol_map.json
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/.meta/project.json
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/.meta/overview_refs.json
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/.meta/aggregate_state.json
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/.meta/source_registry.json
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/.meta/task_bindings/
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/.meta/locks/
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/tasks/.index.json
+.pytest-tmp/test_still_allows_standalone_r0/standalone/repowiki/distill-jobs.json
+
+# 本机专用 qoder 覆盖配置（python3 路径），不提交
+.qoder/settings.local.json
+
+# .scratch 一次性产物不入库：内部工单按 feature 建子目录（.scratch/<feature>/issues/*.md，
+# 见 docs/agents/issue-tracker.md，那些子目录照旧跟踪）；顶层散文件都是发布脚本、命令
+# 输出、迁移备份这类一次性的东西。下面的反选保留子目录，git 才会继续往工单目录里走。
+.scratch/*
+!.scratch/*/

codewiki_plus-5.16.4/.qoder/skills/codewiki-consolidate-knowledge/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-consolidate-knowledge
+description: "lint_wiki 或 wiki_stats 提示 notes_since_last_consolidation 超阈值、出现 aggregation_hint，或用户要求「聚合笔记」时使用（执行前须先询问用户确认）。把已确认笔记聚合为 L2 工作方法场景块（wiki/scenarios/）：prepare 获取待聚合笔记与容量预警 → 撰写/更新场景块 → reject_note 退役被吸收笔记 → submit 记录溯源并归零计数器。"
+# model-invocable
+---
+
+# 知识聚合（L2 场景块）
+
+lint_wiki 或 wiki_stats 提示 notes_since_last_consolidation 超阈值、出现 aggregation_hint，或用户要求「聚合笔记」时使用（执行前须先询问用户确认）。把已确认笔记聚合为 L2 工作方法场景块（wiki/scenarios/）：prepare 获取待聚合笔记与容量预警 → 撰写/更新场景块 → reject_note 退役被吸收笔记 → submit 记录溯源并归零计数器。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="consolidate-knowledge", arguments={"repo_path": "."})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-consolidate-knowledge 触发。

codewiki_plus-5.16.4/.qoder/skills/codewiki-distill-conversations/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-distill-conversations
+description: "检测到 repowiki/raw/ 存在未蒸馏的已采集对话积压时使用（如会话开始提示 pending_raw_count > 0）。把已采集对话蒸馏为双轨产物：notes（通用经验笔记）与 memories（任务进度记忆）。宿主 Agent 充当 LLM：distill_conversation(mode=prepare) 取 transcript → Agent 提取知识 → mode=submit 交回做去重/草稿入库/记忆落盘/评审。全程本地闭环，蒸馏产出的笔记须 confirm_note 确认。"
+# model-invocable
+---
+
+# 蒸馏对话提取记忆和经验
+
+检测到 repowiki/raw/ 存在未蒸馏的已采集对话积压时使用（如会话开始提示 pending_raw_count > 0）。把已采集对话蒸馏为双轨产物：notes（通用经验笔记）与 memories（任务进度记忆）。宿主 Agent 充当 LLM：distill_conversation(mode=prepare) 取 transcript → Agent 提取知识 → mode=submit 交回做去重/草稿入库/记忆落盘/评审。全程本地闭环，蒸馏产出的笔记须 confirm_note 确认。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="distill-conversations", arguments={"repo_path": "."})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-distill-conversations 触发。

codewiki_plus-5.16.4/.qoder/skills/codewiki-ingest-note/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-ingest-note
+description: "完成重要决策、多步调试定位到根因、被用户纠正/吐槽、发现可复用模式后，需要把经验沉淀进知识库时使用。将设计决策、经验教训、架构 rationale、踩坑记录等归档为 8 种笔记类型，自动 BM25 索引，可通过 query_wiki 检索。"
+# model-invocable
+---
+
+# 经验知识归档
+
+完成重要决策、多步调试定位到根因、被用户纠正/吐槽、发现可复用模式后，需要把经验沉淀进知识库时使用。将设计决策、经验教训、架构 rationale、踩坑记录等归档为 8 种笔记类型，自动 BM25 索引，可通过 query_wiki 检索。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="ingest-note", arguments={"repo_path": ".", "note_type": "<note_type>"})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-ingest-note 触发。

codewiki_plus-5.16.4/.qoder/skills/codewiki-promote-note/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-promote-note
+description: "wiki_stats 出现 promotion_candidates 候选、某条 stable 笔记被反复采纳，或用户要求把笔记转正时使用。把候选笔记去个人化重写为正式 wiki 页面：类型路由（pitfall/bug_fix/workaround → query，lesson/decision/architecture → concept）→ write_doc_file 写新页面（必须 draft 状态，写完提醒 confirm）→ edit_doc_file 回标原笔记 metadata.promoted_to。原笔记不删除不降级，保留作审计轨迹锚点。"
+# model-invocable
+---
+
+# 笔记晋升为正式 wiki 页面
+
+wiki_stats 出现 promotion_candidates 候选、某条 stable 笔记被反复采纳，或用户要求把笔记转正时使用。把候选笔记去个人化重写为正式 wiki 页面：类型路由（pitfall/bug_fix/workaround → query，lesson/decision/architecture → concept）→ write_doc_file 写新页面（必须 draft 状态，写完提醒 confirm）→ edit_doc_file 回标原笔记 metadata.promoted_to。原笔记不删除不降级，保留作审计轨迹锚点。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="promote-note", arguments={"note_file": "<note_file>", "repo_path": "."})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-promote-note 触发。

codewiki_plus-5.16.4/.qoder/skills/codewiki-search-wiki/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-search-wiki
+description: "需要检索 Wiki 知识库时使用：编码前查模块文档与架构约定、做决策前查已有 decision 笔记、改文件前查该文件的历史教训。策略指引：BM25 搜索、图谱扩展、深度阅读。"
+# model-invocable
+---
+
+# 知识库搜索
+
+需要检索 Wiki 知识库时使用：编码前查模块文档与架构约定、做决策前查已有 decision 笔记、改文件前查该文件的历史教训。策略指引：BM25 搜索、图谱扩展、深度阅读。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="search-wiki", arguments={"query": "<query>"})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-search-wiki 触发。

codewiki_plus-5.16.4/.qoder/skills/codewiki-skill-creator/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-skill-creator
+description: "用户要求「生成技能」「把经验编成 SKILL」，或 skill_hint 提示某笔记反复被采纳适合编译时使用。把已确认知识（场景块 + stable 笔记 + 技能 open issues）编译为 SKILL.md 行为指令草稿（repowiki/skills/，两区制草稿区：进索引进 lint、不生效）：prepare 取候选素材/冲突预检/容量预警/写作规范 → Agent 撰写 → submit 校验落盘并写双向溯源。install/retire 为后续工单。"
+# model-invocable
+---
+
+# 技能编译（SKILL.md 草稿区）
+
+用户要求「生成技能」「把经验编成 SKILL」，或 skill_hint 提示某笔记反复被采纳适合编译时使用。把已确认知识（场景块 + stable 笔记 + 技能 open issues）编译为 SKILL.md 行为指令草稿（repowiki/skills/，两区制草稿区：进索引进 lint、不生效）：prepare 取候选素材/冲突预检/容量预警/写作规范 → Agent 撰写 → submit 校验落盘并写双向溯源。install/retire 为后续工单。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="skill-creator", arguments={"repo_path": "."})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-skill-creator 触发。

codewiki_plus-5.16.4/.qoder/skills/codewiki-task-workflow/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codewiki-task-workflow
+description: "用户表示「继续上一个任务」「接着上次的干」等跨会话延续工作，或需要创建/关联任务、按 task_id 检索任务上下文时使用。覆盖创建/关联任务、采集对话绑定 task_id、蒸馏时双轨产出笔记与任务记忆、按 task_id 检索与聚合。"
+# model-invocable
+---
+
+# 任务记忆工作流
+
+用户表示「继续上一个任务」「接着上次的干」等跨会话延续工作，或需要创建/关联任务、按 task_id 检索任务上下文时使用。覆盖创建/关联任务、采集对话绑定 task_id、蒸馏时双轨产出笔记与任务记忆、按 task_id 检索与聚合。
+
+调用 MCP 获取完整工作流并按其执行：
+
+```
+get_prompt(name="task-workflow", arguments={"repo_path": "."})
+```
+
+返回的工作流包含分阶段指引，逐步照做即可。
+不要凭记忆执行——模板真源在 `codewiki/mcp/prompts.py`，以 `get_prompt` 返回内容为准。
+本技能可由模型按需自动调用（无 disable-model-invocation），也可由用户显式调用 /codewiki-task-workflow 触发。