本文件面向 FDE(现场交付工程师),说明如何基于本 harness 派生一个交付工程,以及交付过程中哪些能改、哪些不能改。
| 层 | 路径 | FDE 能否改 | 是否 merge 回 upstream |
|---|---|---|---|
| core | src/core/ bin/core/ tests/core/ |
❌ 不要改 | ✅ bug fix 贡献回 upstream |
| custom | src/custom/ bin/custom/ tests/custom/ |
✅ 在这里改 | ❌ 业务特定,不 merge |
| templates | src/templates/ |
❌ 不要改(仅作 diff 参考) | ✅ upstream 演进 |
| config | config/ |
✅ 改 *.local.* |
❌ local 文件 gitignored |
铁律:FDE 只在 custom/ 和 config/*.local.* 里改代码。core 的 bug 修了请走 PR 贡献回 upstream(见 CONTRIBUTING.md)。
cp -r /path/to/dingtalk-opencode-tag /path/to/my-delivery/
cd /path/to/my-delivery/
git init && git add -A && git commit -m "init from harness $(cat VERSION)"记录基线版本(写在 git commit message 里),方便后续同步 upstream 修复时对账。
cp config/config.example.json config/config.local.json
cp config/constants.sh config/constants.local.sh
# 编辑 *.local.* 填入真实 robot_code / user_id / profile / 路径 / proxy_keyconfig.local.json 和 constants.local.sh 已被 .gitignore 忽略,填真实凭据不会误提交。
编辑 src/custom/handler.py(初始内容复制自 src/templates/handler_template.py)。按顺序改:
-
常量正则(顶部):
BUSINESS_MSG_RE/MSGID_RE— 匹配你业务消息的日志格式_RE_MEDIA_ID/_RE_FILE_ID— 匹配附件 ID 格式
-
_classify_message:你的业务消息有几种类型?图片/文件/文本/语音/视频? -
fetch_attachments+_fetch_image_entry+_fetch_file_entry:实现自己的附件下载逻辑(替换 dws CLI 调用为对应平台 SDK)。图片识别 prompt 在agent_common._proxy_vision末句,按业务调整。 -
render_prompt末句:默认是 "请基于上述消息内容回应用户。",改成符合你业务场景的 prompt。 -
回复生成不在 handler 里:handler 只做「消息 → prompt」,生成交给能力调
core.brain.generate_reply(user, prompt, raw=True, ctx={"conv_id": ...})。ctx 必须带 conv_id —— 会话复用按 conv 粒度(AGENT_SESSION_REUSE),不带就退化成每次新建、丢多轮上下文。
业务能力都是 src/custom/capabilities/ 下可组装、可选配的插件。加一个能力 =
写一个模块 + 在 capabilities/__init__.py import 它。不要改 src/core/。
一个能力就是一个 Capability,声明它挂哪些 hook(都可选):
# src/custom/capabilities/my_cap.py
from core.agent_common import submit_handler
from core.capabilities import Capability, register
from core.inbound import InboundMessage, KIND_TEXT, KIND_FORWARD
def on_inbound(msg): # 处理入站消息(InboundMessage)
# msg.user / msg.text / msg.conv_id / msg.msg_id / msg.kind / msg.raw_line
submit_handler(my_handler, msg.msg_id)
return True # True=已消费,registry 不再往下传;False=放行给后续能力
def classify_line(line): # 可选:识别本能力的特殊日志格式(如合并转发 chatRecord)
... # 返回 InboundMessage 或 None;core 只认标准 "收到 @user" 格式
def on_sse_event(event, port, pwd): # 可选:拦截 serve SSE 事件
return False
def on_cleanup(event, state, lock): # 可选:spurious 轮次清理状态机
return False
CAPABILITY = Capability(
name="my_cap", # 开关变量 CAP_MY_CAP_ENABLED
on_inbound=on_inbound,
handles_kinds={KIND_TEXT}, # 只吃这些 kind;空集=全部
classify_line=classify_line, # 不需要就不传
priority=50, # 小的先;catch-all 文本回复用 100 兜底
default_enabled=True,
)
register(CAPABILITY)然后在 src/custom/capabilities/__init__.py 加一行 from custom.capabilities import my_cap。
- 分发:core 的 log-tail 把每行解析成
InboundMessage,按priority依次交给启用 能力,短路于第一个返回 True 的。SSE / cleanup 同理。 - 开关:
CAP_<NAME>_ENABLED(constants.local.sh)。关掉的能力不注册、不参与。 - 顺序:
priority小的先跑(如 Question 交互要先于 catch-all 文本回复拦截用户答案)。 src/custom/routes.py是兼容垫片(旧的 route_* 转调注册表),新增能力不用碰它。
core/event_watcher.py 只认注册表,FDE 永不碰 core → upstream 修复能干净 merge。
src/core/agent_common.py 的 send_notification 默认用 dws CLI 发钉钉消息。如需替换为 Slack / 企业微信 / 飞书 / 邮件,不要直接改 core——在 src/custom/routes.py 里覆盖 send_notification,或在 custom/handler.py 里定义自己的通知函数。
如果通知后端的 bug 在 core 的 send_notification 里(如 dws CLI 调用参数错误),请走 PR 贡献回 upstream。
cp bin/custom/agent-template.plist ~/Library/LaunchAgents/com.<your-org>.<your-agent>.plist
# 编辑 plist:Label / ProgramArguments / StandardOutPath / PATH
launchctl load -w ~/Library/LaunchAgents/com.<your-org>.<your-agent>.plistbash tests/core/unit_test.sh # shell 单测(core,不改)
python3 tests/core/test_agent_common.py # Python 单测(core,不改)
bash tests/custom/e2e_test.sh # 端到端(按业务调整,需要真实链路)当 upstream(本 harness)发布了 core 的修复,FDE 想同步到交付工程:
cd /path/to/my-delivery/
git remote add upstream https://github.com/hugozhu/dingtalk-opencode-tag.git
git fetch upstream
# 只合并 core 层(custom 不受影响)
git merge upstream/main -- src/core/ bin/core/ tests/core/ src/templates/
# 解决冲突(通常无冲突,因为 FDE 没改 core)
git commit -m "sync core from upstream $(cat upstream/VERSION 2>/dev/null)"因为 core 路径在 upstream 和 fork 里完全一致,merge 只会带入 core 的变更,不会污染 custom 的业务定制。
upstream 升级 src/templates/handler_template.py 后,FDE 可 diff 看变化,决定要不要 apply 到自己的 custom/handler.py:
diff src/templates/handler_template.py src/custom/handler.pytemplates 保持纯净,是 FDE diff 的稳定基线。
- serve 密码经
ps可见:find_serve_credentials回退路径从ps eww提取 serve 的AGENT_SERVER_PASSWORD环境变量,.serve.pwd也是明文文件。在多用户主机上,同机其他用户 可通过ps eww/ 读文件看到该密码。仅 localhost basic-auth 场景可接受;若主机有不受信任的其他 用户,请改用 unix socket + 文件权限(chmod 600 .serve.pwd)或短期令牌。同理PROXY_KEY默认sk-1234只是占位,务必在config.local.json换成真实密钥且勿提交。 - 空回复撤回:依赖服务触发 abort 后返回空 finalizer 被发到通知渠道时,event-watcher 无法用机器人身份撤回(钉钉 API "仅消息发送者可撤回" + 缺 processQueryKey)。需要依赖服务端配合过滤空回复。
- macOS 限定:launchd 托管是 macOS 特性。Linux 用 systemd、Windows 用服务/任务计划器,需自己适配
bin/core/monitor.sh。 - 依赖 dws CLI:
send_notification/_run_cli默认用 dws。其他平台在 custom 层覆盖。