AGENT SKILL

write-doc-file-content-file-sidechannel

write_doc_file 建档报目标路径已被手写文件占用/路由冲突时——走 content_file 临时文件侧通道:正文写临时文件→删占位文件→write_doc_file(content_file=...) 正式建档→删临时文件

License 许可
MIT
最近更新
2026-11-13
Stars
★ 21
Forks
4

01 前言 Front Matter

name
write-doc-file-content-file-sidechannel
type
Skill
status
draft
metadata
{ "summary": "write_doc_file 建档遇手写文件占位冲突时的 content_file 侧通道四步流程", "revisions": [ { "at": "2026-09-27T05:07:21Z", "reason": "created from candidate materials", "source": "skill_creator" } ], "source_refs": [ "notes/2026-09-27-write-doc-file-建档遇目标路径已被手写文件占用时走-content-file-临时文件侧通道.md" ] }
generated
{ "at": "2026-09-27T05:07:21Z", "by": "codewiki/5.13.1" }
description
write_doc_file 建档报目标路径已被手写文件占用/路由冲突时——走 content_file 临时文件侧通道:正文写临时文件→删占位文件→write_doc_file(content_file=...) 正式建档→删临时文件
stale_after
1798243200000

03 SKILL.md 正文

工作场景

需要用 CodeWiki 的 write_doc_file 正式建档 wiki 页面(注入 frontmatter、注册交叉链接与索引),但目标路径上已存在手写文件(如先前用 write_to_file 起草的占位稿),直接调用会触发文件路由冲突被拒绝写入。

适用条件

  • 使用 write_doc_file 建档(page_type=module/entity/concept/query/comparison/source 等),且需要工具负责的元数据注入(frontmatter、交叉链接、索引注册)。
  • 目标路径已被手写文件占用,工具报「目标路径已存在 / 路由冲突」类错误。
  • 不适用于普通笔记归档(走 ingest_note,无路径冲突问题);也不适用于编辑已有正式页面(直接 edit_doc_file)。

核心 SOP

依据: notes/2026-09-27-write-doc-file-建档遇目标路径已被手写文件占用时走-content-file-临时文件侧通道.md 的「content_file 侧通道建档流程」(2026-09-25 agentmemory 调研建档实际跑通)。

  1. 把页面正文写入一个临时文件(如 .codebuddy/tmp-<页面名>.md),只写正文、不写 frontmatter——元数据由工具注入;
  2. 删除目标路径上已手写的占位文件(内容已在第 1 步保全,删除无损失);
  3. 调用 write_doc_file(content_file=<临时文件路径>, ...) 让工具从临时文件读正文并正式建档;
  4. 建档成功后删除临时文件,收尾复核新页面 frontmatter 齐全。

判断逻辑

  • write_doc_file 报目标路径冲突 → 先确认冲突文件是手写占位(无工具注入的 frontmatter),是则走侧通道;若已是工具建的正式页面,改用 edit_doc_file 编辑,不要删了重建(会丢 revisions/edit 历史)。
  • 正文很大(接近 MCP 参数限制)→ 更应走 content_file 文件侧通道,顺带规避大载荷内联传输问题。
  • 手写文件内容与拟建页面无关(纯误占位)→ 可直接删,无需第 1 步保全。

禁忌与反模式

  • 勿因冲突就放弃 write_doc_file、让手写文件充当正式页面:缺 frontmatter/索引注册,页面不进检索与 wikilink 图。
  • 勿绕过 dispatch 直连 handler 写文件——路由冲突是确定性簿记在保护建档一致性。
  • 勿把临时文件留在仓库工作树里忘记清理(第 4 步必做)。
  • 勿在临时文件里手写 frontmatter:与工具注入的元数据冲突或产生重复段。

04 同仓库更多 Skills

mambo-wang
mambo-wang/CodeWiki-Plus

windows-python-release

当要手动发布 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 核对

★ 21
mambo-wang
mambo-wang/CodeWiki-Plus

windows-dev-env

Windows/PowerShell 下做 git 写操作、跑子进程或批量文件/测试清理时:shell 漂移与中文路径致命令静默失败、无控制台宿主子进程闪窗、GCM 每次弹 OAuth 框、原生 DLL 被锁——须显式复核落盘、subprocess 加 CREATE_NO_WINDOW、gh auth setup-git 持久化凭据,并用 cmd /c 绕 safe-delete 钩子

★ 21
mambo-wang
mambo-wang/CodeWiki-Plus

repowiki-conclusion-update

已落库 repowiki 结论发生变化时,按「结论方向 vs 表述」分流:方向变则新写 decision 笔记+reject_note 旧+confirm 并回源 ADR,仅表述/证据变则 edit_doc_file 原地改

★ 21
mambo-wang
mambo-wang/CodeWiki-Plus

maintain-fork-pr-merge

当合入 fork 来源的 PR 且 mergeStateStatus=CONFLICTING/DIRTY 时——先 git merge-tree 探测冲突清单,查 maintainer_can_modify,再在 worktree 隔离目录解冲突后 push fork 分支,勿因 CI 绿直接 merge

★ 21
mambo-wang
mambo-wang/CodeWiki-Plus

git-commit-hygiene

在共享 worktree 多会话并行或暂存区有残留时提交代码——用显式 pathspec 只提交自己的文件并排除临时目录,禁止 git add -A 或裸 commit 扫入并行会话的改动

★ 21
mambo-wang
mambo-wang/CodeWiki-Plus

writing-shape

Writing, exploit: shape raw material into an article, paragraph by paragraph.

★ 21