Magic Docs

自动更新的活文档。在 Markdown 文件开头加 `<!-- MAGIC DOC -->` 标记，Agent 会在每轮对话后自动检测是否需要更新该文档，并写入新发现的信息。灵感来自 Claude Code 的 Magic Docs 机制。触发词：magic doc、活文档、自动更新文档、auto doc。

Security Scan

功能与描述大体一致（自动检测并更新带标记的 Markdown 文档），但说明里要求代理自动读取/修改工作区文件、依赖未声明的本地工具，并且对敏感信息的保护只是“规则化”而非强制技术限制，存在潜在风险与不一致之处。

Purpose & Capability

技能目的（维护“活文档”）与大部分运行指令一致：扫描 workspace、判断相关性、修改 Markdown。但 SKILL.md 中显式用到 shell 命令（grep, head）和一个未定义的 `edit` 工具，却在元数据中没有声明所需二进制，这在能力声明上不一致——安装/依赖未被列出。

Instruction Scope

说明要求在每轮对话结束时扫描整个工作区（grep -rl . --include="*.md"），读取文档前 50 行、完整内容，并对文件进行追加或修改。它还建议从 MEMORY.md 和 TOOLS.md 提取信息。读取与修改任意工作区文件属于高权限操作；尽管文档列出“不写入密钥/密码”等安全规则，但没有技术性保障或验证逻辑，容易导致意外写入敏感信息或将对话中暂态/敏感内容落盘。

Install Mechanism

这是 instruction-only 的技能，没有安装步骤或外部下载，因而不会在安装阶段写入磁盘或运行不明二进制，安装风险较低。但运行时依赖本地工具（见 purpose_capability）未声明。

Credentials

技能不要求环境变量或外部凭据，这是合理的。风险在于它会读取工作区中任意文件（包括可能包含凭据的文件）并写回文档，且说明依赖 MEMORY.md/TOOLS.md 等文件——这些未在元数据中声明为受限路径或敏感资源，存在越界读取/写入的可能性。

Persistence & Privilege

虽然没有设置 always:true，且 user-invocable 为 true，但默认行为（update="realtime"）会让代理在每轮对话后自动修改文件，结合自主调用能力（disable-model-invocation=false）意味着技能可能在用户不注意时持续修改工作区文件。自动化修改用户文件应有更严格的确认或审计机制。

What to consider before installing

该技能确实能做“自动维护 Markdown 文档”这类有用工作，但在安装元数据与运行指令间存在不一致，并且会自动读取/修改工作区文件： - 风险点：技能会扫描并写入你的仓库文件，可能无意中记录对话中的敏感信息；它依赖本地命令（grep/head/edit 等）但未声明为必需项；对“不要写入密钥/密码”仅是规则性约束，没有强制检查。 - 建议在安装/启用前采取的步骤： 1) 把默认 update="realtime" 改为 manual 或 daily，以避免每次对话都自动修改文件。 2) 在受控/隔离的测试工作区先试运行，确认行为符合预期并有回滚手段（备份文件/开启版本控制）。 3) 明确限定 scope（只包含非敏感主题），并在 workspace 中对敏感文件（如包含凭据的 MEMORY.md/TOOLS.md）做访问限制或移出工作区。 4) 要求技能在每次写入前征得用户确认，或提供审计日志/变更预览。 5) 如果可能，要求技能作者在元数据中补充所需二进制和明确定义的“edit”工具行为，或用平台提供的受控编辑 API 代替任意文件写入。 总之：该技能功能合情合理，但在自动写入与敏感信息防护上没有技术强制措施，建议谨慎启用并先在受控环境中评估。

Magic Docs — 自动更新的活文档

灵感来源：Claude Code 的 # MAGIC DOC: 机制。

核心问题

文档写完就开始过时。项目变了、API 改了、决策变了——但没人更新文档。 Agent 做了大量操作，学到了很多信息，但这些信息散落在对话里，不会自动沉淀到文档。

什么时候用

主动触发

• 用户说"创建活文档"、"magic doc"、"帮我维护这个文档"
• 用户指定一个 md 文件要求"保持更新"

自动触发（每轮对话结束时）

• 扫描 workspace 中的 Magic Doc 文件
• 判断本轮对话是否包含与该文档相关的新信息
• 如果有 → 自动更新

Magic Doc 标记格式

在任何 Markdown 文件的前 5 行内加入标记：

<!-- MAGIC DOC -->
# 项目架构笔记

记录项目的关键架构决策和技术选型。

可选参数

<!-- MAGIC DOC scope="飞书API,权限配置" -->
<!-- MAGIC DOC scope="设备信息,网络配置" update="daily" -->

• scope：限定关注范围（逗号分隔的关键词），只在对话涉及这些主题时更新
• update：更新频率。realtime（每轮，默认）、daily（每天一次）、manual（只在主动要求时更新）

执行流程

Phase 1 — 发现 Magic Docs

# 扫描 workspace 中的 Magic Doc 文件
grep -rl "<!-- MAGIC DOC" . --include="*.md" | head -20

建立索引：文件路径、scope、update 频率、最后更新时间。

Phase 2 — 相关性判断

对每个 Magic Doc，判断本轮对话是否包含相关的新信息：

1. 读取文档的 scope 和现有内容摘要（前 50 行）
2. 对比本轮对话的主题
3. 判断：是否有文档中还没有的新事实？

判断标准（严格）：

• ✅ 新发现的技术事实（IP 变了、版本升级了、API 改了）
• ✅ 新的决策或约束（"我们决定用 X 不用 Y"）
• ✅ 新的问题和解决方案
• ❌ 对话中只是使用了文档中已有的信息（不算新）
• ❌ 临时的调试过程（不值得记录）

如果判断为"不相关" → 跳过，不更新。

Phase 3 — 智能更新

读取文档完整内容，然后：

1. 追加新信息：在合适的章节下追加，保持文档结构
2. 修正过时信息：如果对话中发现文档内容已过时，直接修正
3. 不重写整个文档：只改需要改的部分，用 edit 工具精确修改
4. 加时间戳：每次更新在修改处加日期标注

## 设备信息

- NAS IP: 192.168.5.27 <!-- updated 2026-04-02 -->
- SSH 密码: 旧密码已失效，新密码见 TOOLS.md <!-- updated 2026-04-02 -->

Phase 4 — 更新日志

在文档末尾维护一个更新日志：

---
## Changelog
- 2026-04-02: 更新 NAS SSH 密码，新增 IMA API 配置
- 2026-04-01: 新增 ESP32 方糖设备信息

创建新的 Magic Doc

当用户要求创建活文档时：

<!-- MAGIC DOC scope="关键词1,关键词2" -->
# [文档标题]

[用户指定的初始内容，或从对话中提取的信息]

---
## Changelog
- YYYY-MM-DD: 初始创建

安全规则

1. 绝不删除用户手写的内容 — 只追加和修正
2. 不写入密钥/密码 — 如果对话中涉及敏感信息，写"见 TOOLS.md"或"见配置文件"
3. 不写入临时调试信息 — 只写确定的、长期有效的事实
4. 保持文档可读性 — 更新后文档应该比更新前更好，不是更乱
5. 冲突时保留两个版本 — 如果不确定哪个是对的，都保留并标注

与其他 Skill 的协作

• Dream：Dream 整理记忆，Magic Docs 整理文档。互补不冲突。
• Context Doctor：Context Doctor 可以检查 Magic Doc 的大小是否影响 context。
• Session Resume：Session Resume 恢复任务状态，Magic Doc 保持文档最新。

使用示例

用户：帮我创建一个活文档，记录所有设备的网络配置
Agent：
1. 创建 devices-network.md
2. 加 <!-- MAGIC DOC scope="IP,SSH,网络,设备" -->
3. 从 MEMORY.md 和 TOOLS.md 中提取现有设备信息写入
4. 此后每次对话涉及设备变更时自动更新

用户：（正常对话中）NAS 的 IP 换成 192.168.5.30 了
Agent：
1. 正常处理用户请求
2. 对话结束时，发现 devices-network.md 是 Magic Doc 且 scope 匹配
3. 自动更新文档中的 NAS IP