AM516/shared/runtime

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. These non-triggering messages are ignored silently: the bridge sends no Feishu reply, makes no API request, and appends no record. Only a message containing exactly one complete, rule-valid eRob model and exactly one positive quantity enters the query workflow. This gate applies even when the bot receives every message in a group; an @mention alone does not bypass it. After a valid initial query, the same sender in the same chat may ask whether there are other candidate models. The bridge keeps that continuation context in memory for six hours, never shares it across senders or chats, and stays silent if no matching context exists. A bridge restart clears the context, so the sender must resend the complete model and quantity. 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.