【Agent】个人 Agent 工作台建设指南

个人 Agent 工作台建设指南

本文说明如何建设一套以「知识、规程、能力、约束」分层的个人 Agent 工作台：既给出与具体产品无关的架构与建设方法，也给出在 Cursor 中的实现方式，并界定资产的作用域与迁移方式。

1. 目标

工作台建成后应满足：

可检索 --- 事实与说明有固定存放位置和入口；
可复现 --- 高频操作有书面规程，触发后结果一致；
可调用 --- 本机命令与外部系统以工具形式接入；
可约束 --- 高风险操作需明确触发，红线持续生效。

建设遵循：分层分离、规程驱动、先可用再增强、高风险显式授权、路径与产物可追溯。

2. 架构

2.1 逻辑结构

text 复制代码

意图（口令 / 提问 / 点名）
        │
        ▼
发现与策略（规程 · 约束）
        │
        ▼
执行（工具 · 脚本 · 连接器）
        │
        ▼
知识（知识库 · 索引 · 项目文档）

层	职责	边界
知识（Knowledge）	事实、说明、细则、索引	不负责任务触发与系统调用
规程（Playbook）	适用场景、步骤顺序、引用文档、选用工具	不代替全局红线；长文细节外置
能力（Tool）	读写、命令、API、检索	不承载业务决策说明
约束（Policy）	持续生效的偏好与禁止项	不编排完整作业流水线
闸门（Gate）	关键节点的强制校验与拦截	不替代日常规程正文

规程只描述如何做；真正执行由运行时的 Agent 调用工具完成。

2.2 规程组织

扁平：一个意图对应一个规程包（默认）。
目录：意图较多时，增加「口令 → 规程」索引包；细则仍在各规程或知识库。

2.3 知识检索级别

级别	能力
L1	目录约定 + 总索引 + 文件搜索
L2	L1 + 专用搜索工具或连接器
L3	外部知识平台 + 连接器

默认建成 L1；检索成本明显上升后再升级。

3. 术语

名称	含义
Agent	依据上下文与规程选择并调用工具的执行体
知识库（KB）	文档、笔记、决策与作业细则的集合
规程包	可发现的作业说明（在 Cursor 中即 Skill）
Runbook	供规程引用的详细步骤
Tool	可调用的能力单元
连接器	将外部系统暴露为 Tool 的适配（如 MCP Server）
约束	常驻或按条件注入的规则
闸门	执行链路上的强制检查
触发	通过口令、点名或引用启动规程

4. 知识库

4.1 目录

text 复制代码

<KB_ROOT>/
├── README.md       # 宗旨、结构、书写约定
├── index.md        # 总索引
├── domains/        # 领域知识
├── runbooks/       # 作业细则
├── decisions/      # 决策记录（可选）
├── snippets/       # 可复用片段（可选）
└── inbox/          # 未整理材料（定期归档）

4.2 约定

一文一题；文首附简短摘要。
文件名可读、可搜索。
新增与废弃文档同步维护 index.md。
密钥与凭证不得写入知识库正文。

4.3 完成标准

知识库可导航；主题可经索引快速定位；inbox 有明确清理周期；默认检索入口已登记。

5. 规程

5.1 内容结构

标识与摘要（做什么、何时用）
适用与不适用
前置条件
步骤（可引用 runbook / 脚本）
产物与成功标准
失败与中止
禁止事项
相关链接

5.2 分类

类型	说明	触发
查询	查阅、解释、归纳	可自动匹配
作业	构建、打包、迁移等	宜显式触发
变更	发布、删除、生产操作等	必须显式触发

能稳定脚本化的步骤应沉淀为脚本，规程中写明调用方式，减少现场拼装命令。

5.3 完成标准

至少具备查询类与作业类规程各一；作业结果可复现；高风险规程在未明确触发时不会执行；与知识库保持单一事实来源。

6. 工具与连接器

能力缺口按以下顺序补齐：运行时内置能力 → 本地脚本 → 现成连接器 → 自研连接器。

每项能力登记：名称、用途、权限、密钥来源、失败表现。规程中写清优先使用的工具及参数约束。

完成标准：清单与实现一致；密钥不进入仓库与知识库正文；至少一条作业规程完整依赖工具跑通。若内置能力已足够，可暂缓连接器，并记录再评估条件。

7. 约束与闸门

将多个规程中重复出现的要求上收为约束。对必须机械拦截的行为配置闸门（例如危险命令、密钥落盘）。

约束解决「默认应如何」；闸门解决「绝对不能怎样」。二者不替代规程中的业务步骤。

8. 建设顺序

按下列顺序推进；前一阶段达标后再扩大范围。

顺序	内容	产出
1	固定路径、命名、高风险清单、密钥策略	配置登记表
2	建设知识库与索引	KB 骨架与示例文档
3	编写规程包与口令对照	可触发的规程
4	接入脚本 / 连接器	工具清单
5	上收约束，必要时加闸门	约束与闸门配置
6	例行检查与变更	持续维护

例行维护： 核对口令与规程是否一致；同步索引；失败案例回写 runbook；废弃项标记并保留短期重定向。

变更： 路径或结构调整时，先更新本文与登记表，再迁移文件，再做口令回归。

9. 角色与交付

角色	职责
建设负责人	架构约定、验收、本文维护
知识管理员	分类、索引、归档
规程作者	规程与 runbook
能力管理员	工具、连接器、密钥注入
使用者	触发与高风险确认

交付物包括：配置登记表、知识库、规程目录与口令对照、工具清单、高风险清单、本文。

配置登记表至少包含：KB 根路径、规程存放位置、默认检索入口、口令对照表、工具清单、高风险清单、最近验收日期。

10. 在 Cursor 中的实现

10.1 映射

本文概念	Cursor
规程包	Skill（`SKILL.md` 目录包）
约束	Rules
工具	内置工具、脚本、MCP Tools
连接器	MCP Server
闸门	Hooks
定时 / 事件驱动执行	Automations

10.2 存放位置

资产	位置	作用域
用户级 Skill	`~/.cursor/skills/<name>/`	本机各工作区
项目级 Skill	`<repo>/.cursor/skills/<name>/`	当前仓库
用户级 MCP	`~/.cursor/mcp.json`	本机各工作区
项目级 MCP	`<repo>/.cursor/mcp.json`	当前仓库
项目级 Rules	`<repo>/.cursor/rules/`	当前仓库
知识库	独立目录或独立仓库	由规程或约束声明入口

~/.cursor/skills-cursor/ 为产品内置目录，不用于存放自定义 Skill。

Skill 目录推荐结构：

text 复制代码

<skill-name>/
├── SKILL.md
├── references/
├── scripts/
└── assets/

SKILL.md 需包含 name 与 description（能力与适用场景）。高风险 Skill 应仅在明确触发时运行。

10.3 实施要点

用 Skill 编排，用内置工具 / 脚本 / MCP 执行。
需要跨仓库复用的规程放用户级 Skill；需要随项目共享的放项目级 Skill。
本机绝对路径（如桌面产物目录）仅适用于本机会话；Automations 等云端执行优先依赖仓库内规程。
首批建议：知识查询 Skill、一项本机作业 Skill；口令增多后再增加目录型 Skill。

11. 适用范围与资产归属

方法与分层（第 2--9 章） 不绑定某一 IDE，可迁移到其它 Agent 运行时。

第 10 章 描述 Cursor 的目录与机制；更换产品时保留方法，替换实现细节。

资产	归属	换设备	换账号
用户级 Skill、用户 MCP、本地知识库	本机文件系统	需备份或同步	一般仍留在原设备
项目级 Skill、Rules、项目 MCP	Git 仓库	克隆即可	与账号无关
对话与部分编辑器设置	视产品同步策略	可能恢复	可能跟随账号
Automations 等云端配置	账号与项目	视云端配置	跟随账号
本机构建产物路径	本机	不迁移	不跟随账号

需要「换机即用」的规程与知识：纳入版本库，或对用户级目录与知识库做明确备份/同步。登录同一账号不等于个人 Skill 与本地知识库自动齐全。

迁移到其它运行时时：迁移知识库 → 改写规程格式 → 重建工具与约束 → 按查询/作业口令做回归。

12. 质量要求

新会话中，约定口令能路由到正确规程。
相同输入下作业结果可复现，或给出明确失败原因。
步骤、路径、产物可在规程或 runbook 中查到。
高风险步骤可中止；失败条件写明。
知识、规程、工具、约束职责清晰，无多重真相。