Initial AM516 Feishu bot package

shared/runtime/README.md

@@ -0,0 +1,54 @@
+# 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.
+- 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.
+
+## 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.