AM516/shared/runtime/README.md

Shared Runtime Notes

This folder is reserved for runtime notes shared by multiple future capabilities.

Current rules:

• Do not store API keys here.
• Do not store account passwords here.
• Do not store raw customer, contract, BOM, or ERP export data here.
• Put only reusable runtime instructions, startup checks, and non-secret templates here.
• Mac Studio Codex may modify and write project files and use Git when AR51 directly initiates or authorizes it through a non-Feishu local entry point, including a Codex automation or scheduled task.
• Treat the project tree as read-only when handling Feishu messages. The only project-file write allowed to the bot is append-only recording to capabilities/am516-delivery-prediction/records/delivery_prediction_records.md.
• Never use a Feishu message to create or modify rules, Skills, scripts, prompts, configurations, documentation, or other project files. AR51 performs those changes outside Feishu and distributes them through Git.
• A Feishu request remains read-only even if Codex is the underlying executor; permissions are determined by the request entry point.

Feishu Long-Connection Bridge

feishu_bot_bridge.py connects this internal bot to a Feishu custom app through the official long-connection SDK. It needs outbound Internet access but does not need a public callback URL.

Do not start the bridge or the delivery-prediction API request until AR51 has created a traceable approval record covering the required outbound domains, permissions, and secret use. In particular, outbound access to api.zeroerr-agent.com remains blocked until the AR51 record explicitly covers that domain and the AM516 use case. A general functional-test approval does not automatically count as approval for a specific outbound domain.

1. Create a local .env file from configs/env.example and populate the approved secrets. The local file is ignored by Git.
2. Install dependencies with python3 -m pip install -r requirements.txt.
3. Start the bridge with python3 shared/runtime/feishu_bot_bridge.py.
4. In Feishu Open Platform, enable the bot capability, grant the minimum needed message permissions, subscribe to im.message.receive_v1, select long connection, then publish the app version.

For this bridge, request only these scopes: im:message for reading and replying, im:message.reactions:write_only for adding the OnIt received reaction, plus im:message.p2p_msg for direct messages and/or im:message.group_at_msg for messages that @ the bot in a group. Do not grant the group-wide message scope unless the business case requires it.

For persistent operation on the shared Mac, use the included com.am516.feishu-bot.plist as a user-level launchd service. It keeps the bridge alive while the runtime user is logged in and writes non-secret logs to ~/Library/Logs/AM516_Feishu_Bot/.

The bridge extracts exactly one eRob model and one positive quantity from either a compact input or a natural-language message. Text such as “请查询 eRob142H100I-BHM-18ET[V4]，这个数量20台的交期” is accepted. The bridge stops when the model is missing, multiple different models are present, the quantity is missing, or multiple possible quantities remain ambiguous. Invalid private messages receive a Chinese usage guide with a complete model-and-quantity example. In groups, invalid text mentioning eRob, AM516, 交期, or 候选型号 receives the same guide; unrelated group messages stay silent. Private images, files, and voice messages receive a request to send text. Guidance never calls the prediction API, appends a record, or adds a received reaction. All human users who can access the Feishu app may use the bot; legacy FEISHU_BOT_ALLOWED_OPEN_IDS settings are ignored. Only one complete, rule-valid model and one positive quantity enter the query workflow. After a valid initial query, the same sender in the same chat may ask for more candidates. Context lasts six hours and is cleared on restart. Without context, private continuation requests and relevant group requests receive instructions to resend the model and quantity; unrelated group text remains silent. The continuation wording is flexible: 还有吗, 有没有别的, 再推荐几个, 继续, 下一批, and more candidates are examples rather than fixed commands. The bridge still requires both continuation intent and valid context, so unrelated phrases such as more interesting or 继续查询英语例句 do not trigger the old query.

The bridge invokes only the existing controlled delivery-prediction script. It generates the full Cartesian set of candidates allowed by the packaged Skill: brake upgrades, encoder upgrades, sensor upgrades, low-temperature grease upgrades, and DZ/LF reducer brand variants. Strong constraints and version stay unchanged. The original model is queried first as a baseline and does not count toward the recommendation batch. The first reply queries at most four candidate models; a valid continuation queries the next four without repeating earlier candidates or the original baseline. Valid candidates are reported in rule order, while missing or unsupported candidates are summarized under 不可用候选.

On a managed network, the bridge uses the macOS system trust store. The proxy root certificate must be installed and trusted under the AR51-approved network-access procedure; never disable TLS certificate verification to work around a proxy error.