Skip to content

Latest commit

 

History

History
158 lines (112 loc) · 7.94 KB

FORKING.md

File metadata and controls

158 lines (112 loc) · 7.94 KB

FORKING.md — FDE 派生交付指南

本文件面向 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)。

派生流程(Step by Step)

Step 1: 复制 harness

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 修复时对账。

Step 2: 填配置

cp config/config.example.json config/config.local.json
cp config/constants.sh config/constants.local.sh
# 编辑 *.local.* 填入真实 robot_code / user_id / profile / 路径 / proxy_key

config.local.json 和 constants.local.sh 已被 .gitignore 忽略,填真实凭据不会误提交。

Step 3: 实现业务 handler

编辑 src/custom/handler.py(初始内容复制自 src/templates/handler_template.py)。按顺序改:

  1. 常量正则(顶部):

    • BUSINESS_MSG_RE / MSGID_RE — 匹配你业务消息的日志格式
    • _RE_MEDIA_ID / _RE_FILE_ID — 匹配附件 ID 格式
  2. _classify_message:你的业务消息有几种类型?图片/文件/文本/语音/视频?

  3. fetch_attachments + _fetch_image_entry + _fetch_file_entry:实现自己的附件下载逻辑(替换 dws CLI 调用为对应平台 SDK)。图片识别 prompt 在 agent_common._proxy_vision 末句,按业务调整。

  4. render_prompt 末句:默认是 "请基于上述消息内容回应用户。",改成符合你业务场景的 prompt。

  5. 回复生成不在 handler 里:handler 只做「消息 → prompt」,生成交给能力调 core.brain.generate_reply(user, prompt, raw=True, ctx={"conv_id": ...})。ctx 必须带 conv_id —— 会话复用按 conv 粒度(AGENT_SESSION_REUSE),不带就退化成每次新建、丢多轮上下文。

Step 4: 写一个能力插件(capability)

业务能力都是 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。

Step 5: 替换通知后端

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。

Step 6: 装 launchd agent

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>.plist

Step 7: 跑测试

bash tests/core/unit_test.sh             # shell 单测(core,不改)
python3 tests/core/test_agent_common.py  # Python 单测(core,不改)
bash tests/custom/e2e_test.sh            # 端到端(按业务调整,需要真实链路)

同步 upstream 修复

当 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 新的最佳实践

upstream 升级 src/templates/handler_template.py 后,FDE 可 diff 看变化,决定要不要 apply 到自己的 custom/handler.py:

diff src/templates/handler_template.py src/custom/handler.py

templates 保持纯净,是 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 层覆盖。