demondamon/agenticx/agenticx-custom-project

AgenticX 定制项目助手

帮人把基于 AgenticX 的项目建对，并在遇到 bug 或新功能时判断：留在自己的仓库，还是给官方提 Issue / PR。判断以本技能目录里的 scripts/custom_project.py 为准，不要凭感觉改结论。

官方仓库是 DemonDamon/AgenticX。产品说明在 agxbuilder.com。三条入口（Python SDK、Near 桌面、企业门户）共用能力，但业务代码不要写进官方仓库。

什么时候用

用用户的原话对照，不必等对方说出「上游」或「运行时」：

什么时候不用

• 只是在 Near 里聊天，不建仓库、不改代码。
• 只想 5 分钟跑通第一个示例智能体。那是快速上手，不是定制项目。
• 用户明确说这次只改业务文案。直接改他们的仓库，不要跑上游流程。

边界

助手按这个顺序做

脚本和本文件在同一技能目录。下文的 python3，在 Windows 上改成 py -3，scripts/custom_project.py 改成 scripts\custom_project.py。脚本自己打印的命令优先照抄。

1. 初始化项目

缺信息时只问这三句，不要一次问一长串：

1. 会不会改 AgenticX 本身的源码？
2. 业务程序是 Python、调用本机服务的其他语言，还是要改 Near 桌面？
3. 这个仓库能不能公开？

然后运行：

python3 scripts/custom_project.py doctor
python3 scripts/custom_project.py plan --mode depend --stack python --name my-agent

--write 只会写业务骨架或一份拷贝记录。它不会克隆官方仓库，也不会改 git remote。目录里已有文件就停止，不覆盖。

agx project create 若问「目录已存在，是否覆盖」，回答否，除非用户明确说可以覆盖。模板名只有 basic、multi_agent、enterprise。

depend 模式：领域 Demo 的默认路径

大多数「基于 AgenticX 做客户或领域 Demo」就是 --mode depend --stack python：用 pip 安装官方发布包（写作时验证过的示例是 agenticx==0.6.5，安装前以 agx --version / PyPI 为准），不要克隆官方源码。闭环全部自研，放在业务仓。典型分层（示意路径，可按项目改名）：

• demo_loop.py 是自检基准：退出码 0、样例断言通过即闭环成立；装了 agx 时可再经 FunctionTool.run 验证工具链。未装 agx 时桥接可返回空工具列表，纯 Python 部分仍可跑。
• 目标目录已非空时，不要强跑 agx project create 覆盖；手工对齐 basic 脚手架精神即可。
• 各业务仓锁定自己验证过的 AgenticX 版本，不必全局统一。

Demo UI 的 localhost 归属

• Demo UI（如 FastAPI 起在 http://127.0.0.1:8765/）是启动服务那台机器上的环回地址。助手若在远程桌面或自己的电脑上启动服务，127.0.0.1 不是用户笔记本的地址。
• 让用户在运行服务那台机器的浏览器里打开，或由助手截图展示。只有服务真的在用户本机时，才说「在你电脑上打开 localhost」。
• Demo UI 的主题、文案、布局是业务 style：--kind style --where business，留在业务仓，不提上游 PR。

Demo UI 默认前端栈（埋在本技能里）

要做本地 Demo 门户或展示页时，默认用 shadcn（常规 UI）+ Bits（动效），共用一套 Tailwind。完整步骤、各框架 registry 与兼容性检查见 references/frontend-ui.md。

快速记忆（React）：

npx shadcn@latest init
# components.json 合并 registries["@react-bits"] = "https://reactbits.dev/r/{name}.json"
npx shadcn@latest add button
npx shadcn@latest add @react-bits/SplitText-TS-TW

组件名以官网变体为准（如 SplitText-TS-TW），不要猜小写串；装前核对 peer 依赖。换皮仍是业务仓：--kind style --where business。

组合其他技能，不合并第三方正文

• 布局文案、品牌规范等仍可另装独立设计类技能，与本技能并列；国内优先经 SkillHub 发现和安装。
• 禁止把第三方设计技能的全文粘进 agenticx-custom-project；本技能只维护上面这套默认前端栈说明。也不要把本技能内容并进别人的技能。
• 安装任何外部技能前，先汇总来源、版本、风险，征得用户确认。

2. 判断 bug 或新功能

把用户的话翻译成参数，然后运行 classify。翻译对照：

不确定「别的用户要不要」时不要猜，让脚本返回提问。

python3 scripts/custom_project.py classify --kind bug --where runtime --cause-clear yes --size small

照抄输出里的「结论」「接下来」「先不要」。不要把「留在本仓」改写成「顺手提一个 PR」。

flowchart TD
  start[收到改动] --> own{只影响这家的文案规则或界面?}
  own -->|是| local[留在自己的仓库]
  own -->|否| ent{门户管理台或网关?}
  ent -->|是| issue[先开 Issue]
  ent -->|否| small{原因清楚的小问题?}
  small -->|是| fix[本仓修复]
  small -->|否| need{别的用户也不看客户规则也需要?}
  need -->|不需要| local
  need -->|还不确定| ask[先问清楚]
  need -->|需要| has{官方是不是已经有了?}
  has -->|已经有| port[升级或最小移植]
  has -->|确认没有| split[通用部分提 PR 业务留下]
  has -->|还没查| check[只查相关目录]

和条款一致的短表：

同一批、同一模块已经查过官方，就复用那个结论。不要每个小任务都查一次。业务可以先交付，不必等官方合并。

3. 写草稿和提交

只有结论允许 Issue 或 PR 时才写草稿。用户提到的客户名称用重复的 --hide 去掉。

python3 scripts/custom_project.py draft \
  --kind issue \
  --title "切换会话后标题变回数字" \
  --summary "从别的会话跳回来，中文标题变成了一串数字。" \
  --expected "仍显示原来的标题。" \
  --actual "显示 session id。" \
  --steps "1. 新建一个只有合成内容的会话。2. 切走再切回来。" \
  --version "0.6.5" \
  --os-name "Windows 11" \
  --hide "客户名称"

草稿在 .agenticx-upstream/ISSUE.md 或 PR.md，并且应被 git 忽略。状态固定是「尚未提交」。

用户已经要求提交时，先不加 --execute 看门禁。通过后再加 --execute。失败就原样报告脚本的「尚未提交」和最后一行原因，不要说已经提交。

python3 scripts/custom_project.py submit \
  --want issue \
  --title "切换会话后标题变回数字" \
  --body-file .agenticx-upstream/ISSUE.md \
  --kind bug --where desktop --can-fix no

提交目标只限 DemonDamon/AgenticX。PR 从功能分支指向 main。分支前缀用 feat/、fix/、docs/。提交说明写原因，不写客户名，不加 AI 工具署名。

使用案例

案例 A：给客户做审批助手，不改框架

用户说：「我们要在自己的仓库里做一个审批助手，用 AgenticX，但不想维护一份框架源码。」

python3 scripts/custom_project.py plan --mode depend --stack python --name approval-helper

脚本结论是：新建业务仓库，用官方发布包装上 AgenticX，不要克隆框架源码。客户规则留在这个仓库。以后的界面文案用 --kind style --where business，结论会是不要给官方提 PR。

若当前 python3 低于 3.10，先读脚本顶部的「注意」。安装命令会改成机器上已有的更高版本；没有更高版本时，先不要 pip。

案例 B：原因清楚的小 bug

用户说：「多窗格里切换模型会串到另一格，我知道是选中状态用了全局变量，改局部就行。」

python3 scripts/custom_project.py classify --kind bug --where desktop --cause-clear yes --size small

实际输出的第一段是：

结论：先在当前仓库修，现在不必给官方提 PR。
原因：根因已经明确的小缺陷，默认在当前仓库修并做定向验证，包括共享运行时里的小修。
业务交付：可以继续，不必等官方合并。

修完并做针对性验证即可。不要为了这一处去扫官方全历史。若这批结束时确认它是大家都会遇到的问题，再和同类小修合成一个 PR。

更多案例（通用新功能、门户只开 Issue、不会改代码、密钥被拦住、GitHub 打不开、领域 Demo 的 depend 闭环与 Demo UI）见 references/examples.md。

出错了怎么办

先看脚本印出的「下一步」，不要把超时当成代码逻辑错误。

完整对照见 references/troubleshooting.md。发布或接手这个技能时，先运行：

python3 scripts/custom_project.py self-test

自检不联网、不提交。失败时它会列出哪一条判断和预期不一致。

常见问题

完整问答见 references/faq.md。

只是用 Near，需要这个技能吗？ 不需要。

改一个按钮文案，要提 PR 吗？ 不要。那是业务仓库的事。

小 bug 已经知道改哪一行，要先把官方仓库搜一遍吗？ 不要。本仓修就行。

GitHub 打不开，新功能还能做吗？ 业务可以先做。通用部分先留草稿，并写上尚未对照最新上游、尚未提交。

门户或网关的 bug 为什么不能直接 PR？ 官方不接受事先没约定的外部 PR，直接提会被关闭。先开 Issue。

草稿写好了，能不能说已经提交？ 不能。只有 submit --execute 成功并返回链接之后才能说已创建。

客户数据能放进复现步骤吗？ 不能。用合成例子。名称用 --hide 去掉。

助手在他的电脑上启动了 Demo UI，我笔记本打不开 127.0.0.1？ 127.0.0.1 是运行服务那台机器的环回。在助手桌面浏览器打开，或让助手截图。详见 references/faq.md。

能把第三方设计技能全文并进这个技能吗？ 不能。默认前端栈（shadcn + Bits）已写在本技能 references/frontend-ui.md；其它设计技能按兄弟技能并列。业务 UI 换皮判 --kind style --where business，不提上游。

各个业务仓必须锁同一个 AgenticX 版本吗？ 不必。各仓库使用自己验证过的版本。

不能违反

条款原文的操作版在 references/upstream-policy.md。仓库里若已有 <!-- agenticx-upstream-policy:start 标记段，按那段执行，不要改写它。

本技能里的文件