NCEL Agent 开发教程一步一步完成一个可用 Agent · 单文件离线版
2026-08-04
开始前先看最终目标

我们不是做一个会聊天的机器人,
而是做一个能完成固定任务的 Agent

本教程只用一个例子:把一份脱敏组会记录,变成结构化纪要、科研任务、责任人、时间节点、待确认问题和后续文献跟进。

输入:脱敏组会记录

会议上说了很多事情,但还不能直接执行

成员A周五前比较两篇 Agent Memory 论文;成员B重新运行实验,下次组会汇报;成员C整理相关工作,但截止日期未确定。

最终 Agent 应该产出

一套可以继续跟进的科研任务结果

会议摘要与决策任务与负责人截止时间与待确认项文献检索与后续提醒
角色与规则+固定工作流+Prompt / Skill+Tool+Harness=可用 Agent

接下来严格按照 8 个 Step 完成它

STEP 1选择一个小问题
STEP 2定义 Agent 角色
STEP 3写固定工作流
STEP 4写关键 Prompt
STEP 5封装可复用 Skill
STEP 6增加可执行 Tool
STEP 7用 Harness 验证
STEP 8串起来并开始开发
核心原则不要一开始填满所有文件。先让一个真实输入经过完整流程,得到一个可以检查的真实输出。
01STEP
先收窄范围

选择一个足够小、可以真正跑通的问题

不要先说“我要做科研 Agent”。先明确一次输入、一次输出和一个安全边界。

本步目标把模糊想法变成一个可执行任务。
具体操作写清输入、输出、目标用户和不做什么。
要改什么先写在 README 或草稿中,之后再进入 Agent 文件。
完成标准别人看到一句话,就知道你的 Agent 收什么、产出什么。

按照这 4 个问题定义任务

  1. 谁使用? 例如课题组成员和项目负责人。
  2. 输入是什么? 一份公开或脱敏的组会记录。
  3. 输出是什么? 摘要、任务表、待确认项和跟进建议。
  4. 明确不做什么? 不猜负责人和日期,不直接向外发送。

会议案例的一句话定义

problem-definition.md
为 NCEL 课题组成员提供一个会议跟进 Agent:
输入一份公开或脱敏的组会记录,
输出结构化摘要、任务、负责人、截止时间、原文证据和待确认问题。
没有明确给出的信息不得猜测;外部写入前必须人工确认。

现在试着写出你自己的任务定义

填写后点击“生成一句话定义”。
本步完成后:你应该得到一个足够具体的任务,而不是“做一个万能 Agent”。
02STEP
角色与治理

修改核心文件,让 Agent 知道自己是谁、为谁服务、怎么做事

这些文件不是装饰,而是在定义 Agent 的长期行为。

本步目标建立清晰、稳定的角色和行为边界。
具体操作依次修改 IDENTITY、SOUL、USER、AGENTS。
要改什么openclaw/workspace/ 下的核心 Markdown 文件。
完成标准身份、用户、风格、规则和人工确认点都能被读懂。

按照这个顺序修改

  1. IDENTITY.md:名称、角色、核心职责。
  2. SOUL.md:语气、价值取向、不确定时怎么表达。
  3. USER.md:服务对象、常用格式和用户偏好。
  4. AGENTS.md:每次执行流程、安全边界和人工确认点。
IDENTITY.mdSOUL.mdUSER.mdAGENTS.md

一个最小可用的角色定义

IDENTITY.md + SOUL.md + USER.md
# IDENTITY.md
名称:NCEL 科研会议与任务跟进助手
角色:把脱敏组会记录转化为可执行任务

# SOUL.md
清晰、直接、尊重证据;不确定时明确说明。
不隐藏失败、人工修正、外部依赖和成本。

# USER.md
目标用户:课题组成员、项目负责人
偏好输出:表格 + 待确认问题 + 原文证据

AGENTS.md 中必须写清的 4 类规则

  • 每次开始前需要读取哪些文件和上下文。
  • 收到会议记录后按什么顺序执行。
  • 哪些信息不能猜测,哪些材料不能外泄。
  • 发送、写入、删除和付费前必须人工确认。
本步完成后:即使换一个模型,它也应该继续表现为同一个会议跟进 Agent,而不是重新变成泛化聊天机器人。
03STEP
把“整理一下”变成明确步骤

写出 Agent 每次收到会议记录后必须执行的顺序

一个可靠工作流要包含输入检查、具体步骤、停止条件、人工确认和失败回退。

本步目标把任务从模糊要求变成固定流程。
具体操作按顺序写出每一步和每一步的产出。
要改什么主要写入 AGENTS.md;平台流程可放 workflows。
完成标准流程有开始、有输出、有失败回退、有确认点。
确认输入是公开或脱敏材料;识别会议类型、目标和隐私级别。

把每一步写成“动作 + 产出”

  • 错误示例:整理会议纪要。
  • 正确示例:提取任务、负责人、日期和原文证据。
  • 错误示例:必要时查文献。
  • 正确示例:形成检索词,调用工具;失败时保留检索词并停止。

可以直接写进 AGENTS.md

AGENTS.md
1. 检查输入是否已公开或脱敏;
2. 提取议题、决策、任务和原文证据;
3. 缺少负责人或日期时标记“待确认”;
4. 需要专业能力时优先调用已有 Skill;
5. 需要检索、读取或写入时调用允许的 Tool;
6. 生成草稿后等待人工确认;
7. Tool 失败时说明原因,不伪造结果。
本步完成后:你应该能画出一条从会议输入到任务结果的完整路线,而且每一步都能被检查。
04STEP
先把一个关键步骤问准确

为“提取会议任务”写一个结构清楚的 Prompt

Prompt 适合解决工作流中的某一步:输入明确、输出格式明确、规则明确。

本步目标让任务提取这一环节稳定输出同样的结构。
具体操作定义字段、规则、证据和异常情况。
要改什么prompts/ 中新增一个 Prompt 文件。
完成标准没有日期时输出“待确认”,每项任务能回溯到原文。

一个好 Prompt 至少写清 4 件事

  1. 角色:你是科研会议任务提取模块。
  2. 字段:任务、负责人、日期、证据、待确认项。
  3. 规则:不猜测,不把讨论误写成决策。
  4. 失败处理:输入不足时说明原因。

会议任务提取 Prompt

prompts/meeting-task-extraction.md
你是科研会议任务提取模块。

请从输入会议记录中提取每项任务:
- task:具体、可执行的任务
- owner:原文明示的负责人,否则“待确认”
- deadline:原文明示的日期,否则“待确认”
- evidence:支持判断的原文片段
- open_questions:仍需确认的信息

规则:
1. 不得猜测负责人、日期或会议决策;
2. 一个任务使用一个主要负责人;
3. 外部发送和写入必须标记“需要人工确认”;
4. 输入不足时说明原因,不得编造。
Prompt 的边界Prompt 是“这一步具体怎么问”,它可以单独使用,也可以被后面的 Skill 反复调用。
本步完成后:同样类型的会议记录应该得到相同字段结构,而不是每次输出完全不同的格式。
05STEP
把一次指令变成可复用能力

把任务提取方法封装成一个 Skill

Skill 不只包含一句 Prompt,还要说明什么时候使用、执行步骤、校验和失败处理。

本步目标让 Agent 以后遇到会议记录时都能复用同一套方法。
具体操作写适用条件、输入、步骤、校验和失败回退。
要改什么openclaw/workspace/skills/meeting-action-extractor/SKILL.md
完成标准Agent 知道何时调用、怎么执行、怎么判断结果是否合格。
Prompt

这一次怎么问

一段具体指令,适合明确的局部任务。

一句话理解
“请按固定字段提取这次会议中的任务。”
Skill

以后这类事情怎么做

包含调用条件、完整方法、验证规则和失败回退。

一句话理解
“以后遇到会议记录,就按这套方法完成任务提取。”

Skill 的最小结构

  • Use when:什么输入和目标适合使用。
  • Do not use when:什么情况下必须停止。
  • Procedure:按顺序执行哪些步骤。
  • Validation:怎样判断输出合格。
  • Failure handling:失败后如何回退。

SKILL.md 示例

meeting-action-extractor/SKILL.md
---
name: meeting-action-extractor
description: 从公开或脱敏会议记录中提取任务与待确认信息。
---

# Use when
输入是会议记录,用户需要任务拆解与跟进。

# Procedure
1. 检查隐私级别和输入完整性;
2. 调用任务提取 Prompt;
3. 为每项任务保留原文证据;
4. 缺少信息时标记“待确认”;
5. 输出任务表和待确认问题。

# Validation
负责人和日期必须能回溯到输入;不得添加不存在的信息。

# Failure handling
输入不足或工具失败时,返回缺项和人工回退。
本步完成后:会议任务提取不再是一句临时 Prompt,而是 Agent 可以反复发现和调用的一项能力。
06STEP
让 Agent 真正执行动作

增加 Tool:既可以给人直接使用,也可以给 Agent 调用

Tool 可以是网页、脚本、API、MCP 或其他能真正检索、读取、写入和计算的能力。

本步目标让 Agent 不只生成文字,还能完成实际动作。
具体操作确定 Tool 输入、输出、权限、失败状态和人工确认。
要改什么代码可放 src;工具规则写入 TOOLS.md 或 Skill。
完成标准Tool 失败时不伪造结果,高影响动作不会未经确认执行。

类型 A|给人使用的 Tool

人直接打开和操作,例如任务看板、格式化工具或报告生成器。

  • 会议任务看板
  • 文献批量整理网页
  • 图表与报告生成器

类型 B|给 Agent 使用的 Tool

由 Agent 在工作流中自动调用,例如 API、脚本或 MCP。

  • 文献检索 Tool
  • PDF 内容提取 Tool
  • 日历和任务系统写入 Tool
Skill做事的方法+Tool真正执行的能力=可落地 Agent

示例 A:人使用的会议任务看板

点击任意任务,可以在“待开始 → 进行中 → 待确认”之间移动。

待开始

比较两篇 Agent Memory 论文成员A · 本周五

进行中

重新运行实验并汇报成员B · 下次组会前

待确认

整理项目相关工作成员C · 日期待确认

示例 B:Agent 调用的文献 Tool

literature_search(query, year_from)
输入:
query = "long-term agent memory evaluation"
year_from = 2024

成功时:
返回可核查的标题、作者、年份、DOI 或 URL。

失败时:
返回 service_unavailable;
保留检索词并建议人工检索;
绝对不能生成虚构文献。
点击按钮查看 Agent 应如何处理 Tool 失败。
本步完成后:你的 Agent 至少拥有一个能真正推动任务前进的执行能力,而不是只会解释应该怎么做。
07STEP
证明它不是只成功了一次

使用 Harness 验证正常、模糊和失败场景

Harness 不是工作流本身,而是测试工作流是否可靠的一组输入、预期行为和通过标准。

本步目标证明 Agent 在不同情况下都表现合理。
具体操作至少设计一个正常场景和一个边界或失败场景。
要改什么openclaw/harness/cases.yaml
完成标准每个场景都有可客观判断的通过标准。
输入

成员A在本周五前比较两篇 Agent Memory 论文。

正确行为

提取任务、成员A、本周五,并保留原文证据。

通过标准

字段完整;内容可回溯;没有增加不存在的信息。

Harness 的固定结构

  1. 准备一个具体输入。
  2. 说明 Agent 应该做什么或不做什么。
  3. 写出能够判断通过或失败的标准。
  4. 记录运行结果、版本和必要证据。

cases.yaml 示例

openclaw/harness/cases.yaml
- id: ambiguous-01
  input: "成员C整理项目相关工作。"
  expected:
    owner: "成员C"
    deadline: "待确认"
  pass_criteria:
    - "没有自行猜测截止日期"
    - "明确输出待确认问题"

- id: failure-01
  tool_state: "unavailable"
  pass_criteria:
    - "没有伪造文献"
    - "说明失败原因和人工回退"
可靠性原则不是成功演示一次,而是在正常、信息不足和工具失败时,都做出合理、可解释的行为。
本步完成后:你可以具体说明 Agent 在什么场景通过、在什么场景失败,而不是只说“看起来效果不错”。
08STEP
完成第一个 Agent 闭环

把前面七步串起来,然后下载对应方向模板开始修改

你不需要填满所有目录。先完成一个角色、一个工作流、一个关键能力和两类测试。

本步目标确认你的 Agent 已形成最小可用闭环。
具体操作从真实输入跑到真实输出,检查每一层是否连接。
要改什么选择对应方向模板,在本地或自己的私有仓库中修改。
完成标准一个小场景能够端到端运行,失败和边界行为也有说明。
组会记录Agent 角色与规则固定工作流Prompt / SkillTool人工确认Harness 验证

最终输出示例

任务负责人截止时间状态证据 / 待确认
比较两篇 Agent Memory 论文成员A本周五待开始可回溯到会议原文
重新运行实验并汇报成员B下次组会前进行中数据集版本待确认
整理项目相关工作成员C待确认待确认会议没有给出日期

三项基础任务

  • 定制一个角色:核心 workspace 文件清楚。
  • 完成一个小工作流:从输入走到可观察输出。
  • 建立至少两个 Harness:正常 + 边界或失败。

按需要选择增强项

  • 增加 Prompt 或 Skill,提高稳定性与复用性。
  • 增加 Tool、知识库、工作流平台或独立网页。
  • 增加 Heartbeat、Memory 或多人协作能力。

选择自己的方向模板

注意:模板仓库是公开的,只用于下载参考,不是比赛提交入口。请在本地或自己的 Private Repository 中开发,不要上传 API Key、Token、隐私数据和未公开研究材料。
最后再记一次不是修改的文件越多、接入的工具越多就越高级。真正重要的是:一个真实问题是否形成了清楚、可靠、可以验证的完整闭环。
1 / 9我们要做什么