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, 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. It 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; 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.