siyu-bank/workphone-sdk

Fork 0

Files

Manus AI f1050dc973 docs: 汇总项目对话问题并增加执行预检

2026-07-28 15:37:00 +08:00

11 KiB

Raw Blame History

工作手机项目：对话与代码重复问题总复盘

日期：2026-07-28 目标：把已经踩过的坑变成一次判断、一次修复、永久复用的项目规则。数据范围：按 Codex session_meta.cwd 严格筛选本项目工作目录，包含活动与归档线程；不读取推理、图片和巨型工具回执。

一、结论

当前效率问题不是“开发人员不够”，而是规则重复广播、多层动作表漂移、源码与运行态漂移、同一故障缺少统一入口。

本次已经落地三个止重复工具：

项目对话分析器：统计真实提问、最终答复、主题和错误。
已知问题唯一台账：错误签名→责任人→固定处理法→禁止重复动作。
执行前只读总门禁：一次检查SDK、设备、Hook、写契约、动作映射和Hook SHA。

二、对话分析结果

2.1 规模

项目	数量
严格属于本工作目录的Codex线程	54
用户/总控输入事件	2,021
已完成轮次	1,607
时间跨度	2026-06-07～2026-07-28
完全相同的“继续”	33次
完全相同的“下一步”	21次
完全相同的“手机已开机，继续”	12次

机器结果：

2.2 最大的无效消耗

codex_delegation / 规则生效 / 经验库生效类内容出现：

1,046条用户/总控输入事件
覆盖37个线程
占2,021条输入事件的51.8%

这些消息主要是在不同线程中反复广播同一套规则、经验、总控要求。规则越长，线程越多，上下文成本越高，而且容易出现新旧版本同时存在。

处理决定：

规则只写入机擎/SKILL.md和known_issue_registry.json。
每个线程启动只读取规则版本号 + 本任务相关问题ID。
只有规则版本发生变化才广播差量，不再广播整段旧规则。

2.3 高频故障

排名	故障	涉及线程	消息命中	判断
1	频控/限流	29	104	多数不是代码Bug，应等待而不是改代码
2	设备离线	20	124	连接主责处理，业务开发停止
3	Hook未附着	17	27	WSS在线不代表Frida RPC可写
4	OpenAPI字段缺失	16	61	运行态契约不完整，首个写请求前停止
5	Unsupported/动作未登记	15	61	Python/Kotlin/JS动作表漂移
6	运行态未加载新代码	12	47	源码已对但进程仍旧，重复改代码无效
7	业务回读失败	6	21	RPC执行不等于微信结果成功
8	502空响应	4	7	网关层首败即停，不继续写动作

每项固定处理方式已经写进已知问题唯一台账。

2.4 跨项目污染

严格按cwd筛选后，仍在9个线程里发现SOUL派对等非工作手机内容。说明问题不是文件筛选，而是同一个工作目录被拿来执行其它项目任务。

后续规则：

工作手机线程只接工作手机、微信控制、SDK、Agent、Hook、接口和验收。
SOUL、房产、网站等任务在自己的项目cwd执行。
跨项目资料只用链接引用，不复制整段上下文到工作手机线程。

三、代码研究结果

3.1 仓库规模异常

指标	数量
Git跟踪文件	221,721
代码文件	610
文档/CSV/JSON	1,091
测试文件	51
`sdk/scripts`跟踪文件	219,659

sdk/scripts占全部Git文件约99.1%，主要来源是gadget_work/wechat_decompiled反编译产物。它会拖慢：

Git状态、差异、索引和提交；
CodeGraph与全文检索；
Agent理解代码时的候选文件质量；
备份和远程同步。

处理建议：把反编译目录作为外部分析资产归档，不继续作为主仓库普通源码跟踪。执行前先做独立备份和Git历史评估，本轮没有直接批量移除22万文件。

3.2 巨型文件和多真源

文件	行数
`sdk/agent/hook/wechat_hook_v2.js`	10,661
`sdk/app/agent/hook/wechat_hook_v2.js`	10,661
`sdk/app/routers/unified.py`	10,209
历史Hook数据脚本	6,803～6,785
Python Agent	2,206 / 2,074

当前三个普通Hook镜像SHA一致，这是好消息；但agent.py、hook_executor.py、frida_manager.py、install.sh在agent/与app/agent/之间已经不同。

这说明“靠人工记得同步”不可持续。正确方案是：

Hook只保留一个可编辑真源。
Android资产、服务端副本、发布包由构建生成。
构建产物携带Git commit、源码SHA、IIFE SHA、APK SHA。
手机Agent注册时上报这些SHA，运行前自动对账。

3.3 动作表分散

动作映射标记分布在至少8个核心文件、129个位置：

Python路由与device_transport
Python Agent与Hook executor
Android Hook executor
JS rpc.exports
Skill动作集合与别名

2026-07-28现场审计结果：

项目	数量
JS RPC exports	218
ACTION_TO_RPC	222
WECHAT_ACTIONS	160
Catalog（含alias）	240
缺失RPC	0
未解析alias	7

未解析项：

add_tag / forward_moments_link / get_contacts_by_label / get_tag_users / get_users_by_tag / moments_post_status / remove_tag

因此，未来新增动作不再分别手改五层；建立一份action_contracts机器真源，再生成各层映射。

3.4 调用链和测试薄弱点

CodeGraph确认核心链为：

unified._execute_skill
→ device_transport.execute_via_ws
→ ws_hub.send_command
→ Android AgentEngine / SkillExecutor
→ FridaBridge / HookExecutor
→ rpc.exports
→ 微信业务回读

CodeGraph同时标记：

两份FridaManager存在双镜像；
Android HookExecutor.execute、SkillExecutor.execute、FridaBridge.execute缺直接覆盖测试；
skill_v2.execute有130个调用方，修改影响面大。

因此测试重点不应该继续堆接口数量，而应优先补：

action contract生成与四层一致性测试；
Android动作分发测试；
Hook attach状态机测试；
最外层四证封装测试；
源码SHA与运行态SHA一致性测试。

四、当前执行前门禁结果

2026-07-28 15:25，本机LAN SDK只读预检：

检查	结果
SDK健康	通过
唯一在线设备	通过，1台
Hook三镜像SHA	通过
真机读操作前置	通过
真机写操作前置	暂停

写操作当前三个阻塞：

capability/frida_hook_not_attached
contract/openapi_write_gate_fields_missing
capability/action_mapping_drift

具体缺口：

/api/v3/wechat/friend-group/execute缺idempotency_key
/api/v3/payment/transfer缺idempotency_key、trace_id
7个动作别名未解析

证据：latest_preflight.json

五、最快执行方案

5.1 从54个历史线程收敛为5个活动角色

活动线程	唯一职责	可改文件域
总控	排序、任务ID、状态、回收	当前状态、任务队列
连接与发布	SDK实例、WSS、APK、运行态	部署与连接脚本
后端与Hook	Agent、Frida、RPC、回读	`sdk/app`、`sdk/agent`、Hook真源
接口契约	OpenAPI、action contract、BFF	请求模型、映射生成器、接口文档
QA证据	只读预检、dry-run、confirm、四证	测试脚本、证据目录

其它历史线程保留只读，不再同时推进。这样不会丢历史，但大幅减少交叉广播和文件冲突。

5.2 每轮固定七步

1. 运行preflight
2. 用blocker匹配known_issue_registry
3. 命中已知问题：直接走canonical_action
4. 未命中问题：只调查一次，生成新issue_id
5. 唯一主责做最小修复
6. 离线测试→受控重载→真机首项→失败即停
7. 更新问题台账、证据和当前状态

5.3 当前最短修复顺序

不占真机先修契约：补好友群聊幂等键、支付幂等键和trace。
不占真机修动作表：解决7个alias并让接口审计全绿。
一次受控部署：记录commit、进程时间、Hook/IIFE/APK SHA。
恢复Hook：只处理session/PID/RPC状态，不混入业务修复。
QA首项验证：读→dry-run→confirm→回读→同键幂等；失败即停。
批量放行：首项四证完整后再继续后续编号。

六、以后怎么避免重复优化

开始前

python3 sdk/scripts/workphone_execution_preflight.py

返回ready_for_write=false时，只处理blockers，不执行微信写操作。

查历史问题

优先打开：

更新对话分析

开发文档/10、项目管理/scripts/run_workphone_conversation_analysis.sh

该命令按cwd重新扫描活动与归档线程，只抽取真实用户消息和最终答复，不加载图片、工具回执和推理。

七、完成标准

规则重复广播由整段复制改为版本号引用。
活动线程最多5个，每个文件只有一个主责。
执行前总门禁无阻塞后才做真机写入。
动作表审计为0个未解析别名。
四类写接口统一具备dry_run / confirm / idempotency_key / trace_id。
Hook源码、IIFE、APK和手机运行态SHA可自动对账。
已知问题命中后直接执行固定方案，不再从头调查。

11 KiB Raw Blame History Unescape Escape